Troubleshooting

Address already in use

listen tcp :3488: bind: address already in use

Another process is already using the port.

Check whether CH-UI is already running:

ch-ui server status

Then stop the old process:

ch-ui server stop

If status says the PID file is missing but the port is in use, you likely upgraded from an older binary without PID management. Stop the old process once, then restart with the current build.

Connector auth failures (`invalid token`)

Verify you copied the latest cht_... token.
Check active connections with ch-ui tunnel list.
Regenerate with ch-ui tunnel rotate <connection-id> (or create a new one with ch-ui tunnel create --name ...).
Confirm the agent uses the correct --url and token pair.

CH-UI surfaces explicit login states (invalid credentials, offline connection, retry window). If login fails:

Verify the selected connection is online.
Confirm ClickHouse credentials are correct for that connection.
Check connector logs for upstream errors.

Rate-limit lockouts are progressive and capped:

1st lock: 3 minutes
2nd lock: 5 minutes
3rd+ lock: 10 minutes (cap)

If local URL/connection setup is wrong, restart CH-UI with explicit values:

ch-ui server --clickhouse-url http://127.0.0.1:8123 --connection-name "My Connection 1"

Environment-variable equivalent:

CLICKHOUSE_URL=http://127.0.0.1:8123 CONNECTION_NAME="My Connection 1" ch-ui server

Docker:

docker run --rm -p 3488:3488 -v ch-ui-data:/app/data \
  -e CLICKHOUSE_URL='http://127.0.0.1:8123' \
  -e CONNECTION_NAME='My Connection 1' \
  ghcr.io/caioricciuti/ch-ui:latest

Full guide: Can't Login?

WebSocket / tunnel fails behind proxy

Your reverse proxy must forward WebSocket upgrades on /connect:

Pass Upgrade and Connection: upgrade headers.
Set long read/send timeouts (e.g. proxy_read_timeout 3600).
Disable buffering for the tunnel path.

Example Nginx config for the /connect path:

location /connect {
    proxy_pass http://127.0.0.1:3488/connect;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600;
}

Health check

Use the health endpoint to verify the server is running:

curl http://localhost:3488/health

Cloud-Specific Issues

Magic link not arriving

Check your spam/junk folder.
Rate limits apply: 10 requests per IP and 3 per email per 15 minutes. Wait and try again.
Verify you entered the correct email address.

Connection shows offline in Console

Verify the connector is running on the ClickHouse host: check process or service logs.
Confirm the tunnel token matches — regenerate from the Console if in doubt.
Check outbound connectivity from the connector host to wss://your-org.ch-ui.com/connect.
The Console polls every 15 seconds — wait a moment after starting the connector.

Ensure at least one connection is online in the Console.
Verify your ClickHouse credentials are valid for the connected instance.
Check that your org member role has sufficient permissions.

Org or connection limit reached

Your plan determines the maximum number of connections. Check the billing page in the Console.
To add more connections, upgrade your plan or contact support.

On this page