ContextDx
Self-Hosted

Trouble shooting guide

This guide helps you diagnose and resolve common issues with your ContextDX deployment

ContextDX Troubleshooting Guide

This guide helps you diagnose and resolve common issues with your ContextDX 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:

Service Won't Start

Symptoms

  • docker compose up fails
  • Containers exit immediately after starting

Diagnosis

Check logs:

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

Common Causes & Solutions

CauseSolution
Missing credentials in .envVerify CDX_DEPLOYMENT_ID and CDX_DEPLOYMENT_SECRET are set
Port already in useChange CDX_PORT in .env or stop conflicting service
Insufficient disk spaceFree up disk space (need 20GB minimum)
Docker not runningStart Docker Desktop or docker daemon

Commands to Try

BASH
# 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.

BASH
# 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

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

  2. Proxy not routing correctly

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

  3. Network issue between containers

    BASH
    # 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

BASH
# 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:

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

  2. Wait for healthy status, then restart server:

    BASH
    # 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:
    BASH
    # 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

BASH
# 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:

    BASH
    ping portal.contextdx.com

  2. Verify HTTPS is not blocked:

    BASH
    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_DEPLOYMENT_ID and CDX_DEPLOYMENT_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:

BASH
# Linux/Mac
sudo lsof -i :80

# Windows
netstat -ano | findstr :80

Solutions

Option 1: Stop conflicting service

BASH
# Example: stop Apache
sudo systemctl stop apache2

# Example: stop nginx
sudo systemctl stop nginx

Option 2: Use a different port

BASH
# 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

BASH
# 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

CauseSolution
Database not readyWait for postgres to be healthy, then restart server
Invalid configurationCheck .env file for syntax errors
Out of memoryIncrease available RAM or reduce other workloads
Dependency container unhealthyRestart all services in order

Recovery Steps

BASH
# 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:

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

  2. Ensure no extra spaces or quotes:

    BASH
    # Correct
CDX_DEPLOYMENT_ID=dep_abc123xyz

# Wrong
CDX_DEPLOYMENT_ID="dep_abc123xyz"
CDX_DEPLOYMENT_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.

Warning: This deletes ALL data including the database!

BASH
# 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

BASH
# 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

BASH
# 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

Quick Reference Commands

IssueCommand
Check all container statusdocker compose -f docker-compose.production.yml ps
View server logsdocker compose -f docker-compose.production.yml logs server
View all logsdocker compose -f docker-compose.production.yml logs
Restart all servicesdocker compose -f docker-compose.production.yml restart
Restart single servicedocker compose -f docker-compose.production.yml restart <service>
Stop all servicesdocker compose -f docker-compose.production.yml down
Full reset (loses data)docker compose -f docker-compose.production.yml down -v
Shell into containerdocker compose -f docker-compose.production.yml exec server sh