Troubleshooting & Support

Diagnose and resolve common installation hurdles, database migrations, WebSocket connections, and contact technical support.

WebSocket Connection Refused (1006) & Dropouts

If real-time messages, typing indicators, or presence indicators fail to update, your reverse proxy is likely terminating or failing to upgrade the WebSocket connection.

1. Configure Nginx Upgrade & Long-Lived Timeouts

Ensure proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; are defined in your server block, along with long read/send timeouts so idle chat sockets are not disconnected:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Keep idle WebSocket connections open for 24 hours:
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
}

2. Enable Cloudflare WebSockets

In your Cloudflare Dashboard, go to Network > WebSockets and ensure the toggle is turned ON. Cloudflare proxies require this toggle to route WSS upgrade handshakes.

3. Verify Secure Protocol (WSS vs WS)

Modern browsers enforce mixed-content blocking. If your site is loaded over https://, the WebSocket URL must use wss://. Ensure JCHAT_SITE_URL in your .env starts with https:// in production.

Database Connection & Schema Migration Errors

If JChat fails on boot with database connection errors (ECONNREFUSED or authentication failures), or if new features report missing tables or columns:

1. Validate Database Connection URI

Confirm JCHAT_DATABASE_URL matches the running PostgreSQL service. In Docker Compose networks, the hostname must be db rather than localhost:

JCHAT_DATABASE_URL=postgresql://jchat:jchat_secret@db:5432/jchat

2. Execute Pending Migrations

If you updated JChat or installed an addon with database requirements, apply pending database migrations:

bun db:migrate

3. PostgreSQL Connection Limits

Ensure max_connections in your postgresql.conf is configured to at least 100 to handle multi-worker connection pooling.

Redis Connection Timeouts & Dropped Events

JChat utilizes Redis Pub/Sub for inter-node message broadcasting and background outbox event processing. Verify that Redis is accessible and configured correctly:

1. Test Redis Connectivity

Ping the Redis instance from inside the app container or host terminal:

redis-cli -u redis://localhost:6379 ping
# Should return PONG

2. Set Memory Eviction Policy to noeviction

In redis.conf, set maxmemory-policy noeviction so Redis never evicts active Pub/Sub channels or session tokens under memory pressure.

CORS, 403 Forbidden & Multi-Tenant Routing

JChat routes requests between tenant chat instances and the Owner Control Panel (/owner). If you experience 403 Forbidden errors or unexpected redirects:

1. Forward Proxy Host & Protocol Headers

Reverse proxies must pass the original Host header and forwarding protocol so ElysiaJS and React Router SSR can reconstruct origin headers accurately:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

2. Accessing the Owner Control Panel

The Owner Control Panel is mounted at /owner on your primary apex domain. Tenant sites are accessed via their provisioned slug or custom CNAME domain.

Application Returns 503 Service Unavailable

A 503 error on boot indicates a domain configuration mismatch, an unbound license key, or that the application is awaiting initial setup.

1. Verify Domain and Configuration

Ensure the domain configured in your .env file (JCHAT_DOMAIN) matches the apex domain registered with your license key. Check application startup logs to pinpoint the issue:

docker compose logs --tail=100 jchat

2. Verify Data Directory Permissions

Ensure your persistent data directory (or Docker volume) is writable by the application process so that local configuration can be saved across container restarts:

# Check data directory permissions:
ls -ld data

3. Re-bind Domain via Customer Portal

If you migrated servers or changed domains, log into the JChat Store Customer Portal to release the previous domain binding and activate your new domain.

File Upload Failures & 413 Payload Too Large

If avatar uploads or media attachments (images, PDFs, audio notes) fail with error 413 or permission issues:

1. Increase Nginx Client Max Body Size

Nginx defaults to a 1MB request body limit. Increase client_max_body_size in your Nginx http or server block:

client_max_body_size 50M;

2. Verify Directory Permissions

If using local filesystem storage (JCHAT_STORAGE_TYPE="LOCAL"), ensure the uploads/ directory has write permissions for the container process UID (1000:1000):

chown -R 1000:1000 ./uploads && chmod -R 755 ./uploads

# Export sanitized startup and runtime logs:
docker compose logs --tail=200 jchat > jchat_debug.log

# Check system and environment details:
bun --version
docker --version
uname -a