Troubleshooting Guide

This guide helps you diagnose and resolve common issues with your self-hosted deployment.

Table of Contents

1. Service Won't Start
2. Configuration Error on Web Page
3. Database Connection Failed
4. Can't Connect to Portal
5. Port Already in Use
6. Container Keeps Restarting
7. Invalid Deployment Credentials
8. Subscription Issues
9. Reset Everything
10. Collecting Logs for Support

Related Guides:

• Installation Guide
• Backup & Restore Guide
• SSL & Reverse Proxy Guide

Service Won't Start

Symptoms

• docker compose up fails
• Containers exit immediately after starting

Diagnosis

Check logs:

docker compose -f docker-compose.production.yml logs server
docker compose -f docker-compose.production.yml logs web

Common Causes & Solutions

Commands to Try

# Check detailed logs
docker compose -f docker-compose.production.yml logs

# Verify Docker is running
docker info

# Check available disk space
df -h

# Try recreating containers
docker compose -f docker-compose.production.yml down
docker compose -f docker-compose.production.yml up -d

Configuration Error on Web Page

Symptoms

• Web page shows "Configuration Error"
• API calls fail with network errors

Diagnosis

The web app can't reach the backend server.

# Is server healthy?
docker compose -f docker-compose.production.yml ps server

# Can you reach the backend health endpoint?
curl http://localhost/health

# Can you reach the config endpoint?
curl http://localhost/api/config/public

Common Causes & Solutions

1. Server container not running

   BASHCopy

   docker compose -f docker-compose.production.yml restart server

2. Proxy not routing correctly

   BASHCopy

   docker compose -f docker-compose.production.yml restart proxy

3. Network issue between containers

   BASHCopy

   # Recreate the network
   docker compose -f docker-compose.production.yml down
   docker compose -f docker-compose.production.yml up -d

Database Connection Failed

Symptoms

• Server logs show: Error: connect ECONNREFUSED
• Server fails to start

Diagnosis

# Check postgres container status
docker compose -f docker-compose.production.yml ps postgres

# Check postgres logs
docker compose -f docker-compose.production.yml logs postgres

Solutions

1. Restart postgres:

   BASHCopy

   docker compose -f docker-compose.production.yml restart postgres

2. Wait for healthy status, then restart server:

   BASHCopy

   # Wait for postgres to be healthy
   docker compose -f docker-compose.production.yml ps postgres
   
   # Then restart server
   docker compose -f docker-compose.production.yml restart server

3. Verify password matches:

   • Check CDX_DATABASE_PASSWORD in .env
   • If you changed the password, you may need to recreate the database:
   BASHCopy

   # WARNING: This deletes all data!
   docker compose -f docker-compose.production.yml down -v
   docker compose -f docker-compose.production.yml up -d

Can't Connect to Portal

Symptoms

• Server starts but shows degraded status
• Logs show: Network error: fetch failed
• License validation fails

Diagnosis

# Test network connectivity from server container
docker compose -f docker-compose.production.yml exec server \
  wget -qO- https://portal.contextdx.com/health

Solutions

1. Check internet connectivity:

   BASHCopy

   ping portal.contextdx.com

2. Verify HTTPS is not blocked:

   BASHCopy

   curl -I https://portal.contextdx.com

3. Check firewall rules:

   • Ensure outbound port 443 (HTTPS) is allowed
   • Whitelist portal.contextdx.com if using a proxy

4. Verify credentials:

   • Check CDX_APP_ID and CDX_APP_SECRET in .env
   • Ensure deployment is active in Portal dashboard

Port Already in Use

Symptoms

• Error: port is already allocated
• Container fails to start

Diagnosis

Find what's using port 80:

# Linux/Mac
sudo lsof -i :80

# Windows
netstat -ano | findstr :80

Solutions

Option 1: Stop conflicting service

# Example: stop Apache
sudo systemctl stop apache2

# Example: stop nginx
sudo systemctl stop nginx

Option 2: Use a different port

# Edit .env
CDX_PORT=8080

# Restart
docker compose -f docker-compose.production.yml down
docker compose -f docker-compose.production.yml up -d

Container Keeps Restarting

Symptoms

• Container status shows "Restarting"
• Health checks failing

Diagnosis

# Check logs for errors
docker compose -f docker-compose.production.yml logs --tail=100 server

# Check container status
docker compose -f docker-compose.production.yml ps

Common Causes & Solutions

Recovery Steps

# Stop everything
docker compose -f docker-compose.production.yml down

# Start in order with health check waiting
docker compose -f docker-compose.production.yml up -d postgres
# Wait for postgres to be healthy
docker compose -f docker-compose.production.yml ps postgres

docker compose -f docker-compose.production.yml up -d server
# Wait for server to be healthy
docker compose -f docker-compose.production.yml ps server

docker compose -f docker-compose.production.yml up -d

Invalid Deployment Credentials

Symptoms

• Server fails to start
• Logs show: Deployment activation failed: invalid_credentials

Solutions

1. Double-check credentials in .env:

   BASHCopy

   # View current values (careful not to expose these!)
   grep CDX_DEPLOYMENT .env

2. Ensure no extra spaces or quotes:

   BASHCopy

   # Correct
   CDX_APP_ID=dep_abc123xyz
   
   # Wrong
   CDX_APP_ID="dep_abc123xyz"
   CDX_APP_ID= dep_abc123xyz

3. If credentials were regenerated in Portal:

   • Get new credentials from Portal dashboard
   • Update .env with new values
   • Restart: docker compose -f docker-compose.production.yml restart server

Subscription Issues

Subscription Inactive

Symptoms:

• Logs show: Subscription inactive or suspended

Solutions:

1. Log in to Portal dashboard
2. Check Billing section
3. Update payment method if needed
4. Once resolved, restart: docker compose -f docker-compose.production.yml restart server

Seat Limit Reached

Symptoms:

• New users cannot log in
• Error: 403 Forbidden: Seat limit reached

Solutions:

1. Wait for inactive sessions to expire (automatic)
2. Upgrade to a higher plan in Portal
3. Remove inactive users from your organization

Reset Everything

If all else fails, you can reset to a clean state.

Caution

This deletes ALL data including the database!

# Stop and remove everything including volumes
docker compose -f docker-compose.production.yml down -v

# Remove any cached images (optional)
docker system prune -a

# Start fresh
docker compose -f docker-compose.production.yml up -d

Collecting Logs for Support

When contacting support, include the following information:

Quick Log Collection

# Save all logs to a file
docker compose -f docker-compose.production.yml logs > contextdx-logs.txt 2>&1

# Include service status
docker compose -f docker-compose.production.yml ps >> contextdx-logs.txt

# Include configuration (without secrets!)
grep -v SECRET .env | grep -v PASSWORD >> contextdx-logs.txt

Detailed Diagnostics

# Docker version
docker --version >> contextdx-logs.txt
docker compose version >> contextdx-logs.txt

# System info
uname -a >> contextdx-logs.txt

# Disk space
df -h >> contextdx-logs.txt

# Memory
free -h >> contextdx-logs.txt

What to Include in Support Requests

1. contextdx-logs.txt (from commands above)
2. Error messages you're seeing
3. Steps to reproduce the issue
4. When the issue started (after an update, configuration change, etc.)

Support Channels

• Documentation: https://docs.contextdx.com
• Portal Dashboard: https://portal.contextdx.com
• Email Support: support@contextdx.com

Quick Reference Commands