chmonitorConnection errors
Fix "Test connection" failures in chmonitor — host not allowed, invalid URL, authentication failed, missing permissions, DNS, refused, TLS, and timeout errors.
When you add a ClickHouse host and click Test connection, the dashboard classifies any failure into one of the kinds below and links you straight here. Find your error and follow the fix.
Fix your error
Each entry lists the message you saw (the symptom) and the fix. The dashboard shows the raw ClickHouse or network error as technical detail underneath the classified error.
Postgres connections
Postgres sources (behind the CHM_FEATURE_POSTGRES_SOURCE feature flag) connect
over a raw TCP driver rather than HTTP, so the Test connection flow reports
the Postgres driver's own errors — identified by their five-character
SQLSTATE code.
They map to the same error kinds above:
| Symptom | SQLSTATE | Kind | Fix |
|---|---|---|---|
| password authentication failed for user… | 28P01 / 28000 | Authentication failed | Re-check the username and password. Postgres roles are case-sensitive. |
| database "…" does not exist | 3D000 | Database not found | Enter an existing database name (case-sensitive), or create it on the server. |
| connection to server … failed · ECONNREFUSED | 08006 / 08001 | Connection refused | Confirm the port (usually 5432), that Postgres accepts external connections (listen_addresses, pg_hba.conf), and that the firewall allows the dashboard. |
| the server does not support SSL connections | — | TLS / certificate error | The server has TLS disabled but the connection requires it. Set SSL mode to disable, or enable TLS on the server. |
| Connection timeout expired | — | Connection timed out | Confirm the host is publicly reachable and inbound traffic is allowed on the Postgres port. |
Postgres monitoring is read-only
Every Postgres session the dashboard opens is pinned read-only
(default_transaction_read_only = on) and only single SELECT / WITH /
SHOW / EXPLAIN statements are allowed — the connection can never write. Use
the SSL mode selector (require by default, verify-full to verify the
certificate, disable for a plaintext local socket) to match your server.
For private Postgres hosts (localhost, 10.x, 192.168.x), the same SSRF
rule applies as for ClickHouse: self-host chmonitor and set
CHM_ALLOW_PRIVATE_HOSTS=true. Reproduce a failure outside the dashboard with
psql "postgres://user:pass@host:5432/db".
Still stuck?
Reproduce the failure with curl
Test the same URL and credentials outside the dashboard to isolate whether it's a network or a credentials problem:
echo 'SELECT version()' | curl "https://host:8443/?user=monitoring&password=…" --data-binary @-For private clusters, self-host chmonitor — the same dashboard, with no public-network requirement.
Related
Troubleshooting
Diagnose connection, auth, performance, and Kubernetes probe failures.
ClickHouse requirements
The least-privilege monitoring user and grants the dashboard needs.
Connect a firewalled ClickHouse
Reach a firewalled cluster from Cloud with a tunnel or dedicated egress IPs.
Self-host
Run chmonitor inside your network with no public-address restriction.
Connect a firewalled ClickHouse or Postgres (Cloud)
Connect a firewalled ClickHouse or Postgres to chmonitor Cloud — Cloudflare Tunnel (recommended), dedicated egress IPs for allowlisting, jump host, and why allowlisting Cloudflare's shared ranges does not work.
Troubleshooting
Diagnose and fix common chmonitor issues — connection failures, auth errors, performance problems, and Kubernetes probe failures.