Skip to content
chmonitor chmonitor

FAQ

Open as Markdown

Connection issues

Section titled “Connection issues”

The dashboard shows a connection error.

Check that CLICKHOUSE_HOST is a full URL including scheme and port, e.g. http://your-host:8123 or https://your-host:8443. Inside Docker, localhost points at the container itself — use the ClickHouse service name on the Docker network, or host.docker.internal (Mac/Windows) / 172.17.0.1 (Linux) to reach a process on the Docker host.

I changed ClickHouse credentials but the dashboard still fails.

Restart or redeploy the app after updating credentials. For Cloudflare Workers, run bun run cf:config to push the new secrets, then redeploy (bun run cf:deploy). The worker connection pool caches credentials at startup.

System tables and empty pages

Section titled “System tables and empty pages”

Some pages are empty or show “table not found”.

The page depends on a ClickHouse system table that is disabled or not present in your version. See Enable system tables to check which tables are required and how to enable them.

The query thread analysis page is empty.

system.query_thread_log must be explicitly enabled in ClickHouse config and log_query_threads=1 must be set in the profile used by the monitoring user. See the Enable system tables guide.

ZooKeeper / Keeper pages are missing.

system.zookeeper only exists when ClickHouse Keeper or ZooKeeper is configured. If you don’t use a replicated setup, these pages will not show data.

Authentication

Section titled “Authentication”

How do I require login before anyone can use the dashboard?

Set CHM_AUTH_PROVIDER=clerk and configure Clerk keys, then set CHM_AUTH_REQUIRED_FEATURES=agent,mcp,settings,actions (or use CHM_FEATURE_{ID}_ACCESS=authenticated per feature). See Authentication.

I want to protect specific features but not the whole dashboard.

Use per-feature env vars:

Terminal window
CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_FEATURE_MCP_ACCESS=authenticated

The AI agent is accessible without login. Is that safe?

The agent uses the same ClickHouse grants as the configured monitoring user. If that user is read-only, the agent can only read. If you want to restrict it further, set CHM_FEATURE_AGENT_ACCESS=authenticated.

Multi-host

Section titled “Multi-host”

How do I monitor multiple ClickHouse clusters?

Set CLICKHOUSE_HOST to a comma-separated list of host URLs. For credentials, you can provide a single value (applied to all hosts) or one value per host position. CLICKHOUSE_NAME is optional (hosts default to indexed labels):

Terminal window
CLICKHOUSE_HOST=https://prod-a:8443,https://prod-b:8443
CLICKHOUSE_USER=monitoring,monitoring
CLICKHOUSE_PASSWORD=secret-a,secret-b
CLICKHOUSE_NAME=prod-a,prod-b

A host selector appears in the UI when more than one host is configured.

AI agent

Section titled “AI agent”

The agent returns errors or doesn’t respond.

Check that LLM_API_KEY is set and that LLM_API_BASE points at a reachable OpenAI-compatible endpoint. The agent uses https://openrouter.ai/api/v1 by default. Verify the key works by testing the endpoint directly. Also confirm the feature is not disabled (CHM_FEATURE_AGENT_ENABLED=false would silence it).

The agent can’t kill queries or run OPTIMIZE.

AGENT_ENABLE_CONTROL_TOOLS defaults to false. Set it to true only if you intend to let the agent use those actions, and only when the ClickHouse user has the corresponding grants (KILL QUERY, OPTIMIZE).

Conversation persistence

Section titled “Conversation persistence”

Agent conversation history disappears after I close the browser.

By default, history lives in browser localStorage. To persist it server-side:

  1. Set VITE_FEATURE_CONVERSATION_DB=true at build time (before bun run build). Also requires Clerk auth.
  2. Set CONVERSATION_STORE_BACKEND at runtime to agentstate, d1, postgres, or memory.

See Conversation History and Store Backends.

Data freshness

Section titled “Data freshness”

The dashboard shows stale data.

The TanStack app revalidates data on focus and on a polling interval. Reduce CLICKHOUSE_MAX_EXECUTION_TIME if queries are taking too long, or adjust the client-side refresh interval per chart.

Deployment

Section titled “Deployment”

Which deployment should I use?

  • Docker — simplest self-hosted path, works anywhere Docker runs.
  • Kubernetes — best when the dashboard is managed alongside your platform workloads.
  • Cloudflare Workers — edge hosting, no server to operate, works well with Cloudflare Access for auth.
  • Vercel / self-host Node — if you prefer a Node-based platform.

See Install & Configure for platform-specific guides.