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.

Login fails

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

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

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