Reference & help
Troubleshooting
Common failure modes — login, connections, migrations, SSO, MCP — and how to diagnose them.
Find the symptom, check the cause, apply the fix. Server logs are JSON (Pino) on stdout; most problems name themselves there.
Sign-in & sessions
| Symptom | Cause | Fix |
|---|---|---|
| Default login rejected | The seeded admin is only created with a new RBAC database; its password may have been changed | Sign in as another admin and reset it in Admin › Users |
| "Password sign-in is disabled" | AUTH_PASSWORD_LOGIN_ENABLED=false with a working SSO provider | Use SSO, or set it back to true |
| Signed out after a deploy, or randomly with several replicas | JWT_SECRET differs between pods or changed | Use one fixed secret everywhere — see Sessions & JWT |
| SSO button missing | AUTH_SSO_ENABLED is not true, or no valid provider | See SSO |
| SSO callback fails | Redirect URI at the IdP ≠ <AUTH_SSO_BASE_URL>/auth/sso/callback | Make them identical |
| SSO change not visible on some pods | Propagation interval | Wait AUTH_CONFIG_WATCH_INTERVAL_MS (15 s by default) |
Connections & queries
| Symptom | Cause | Fix |
|---|---|---|
| Connection refused | ClickHouse isn't reachable from the server container | Use a host the server can reach (in Compose, the service name such as clickhouse-server:8123, not localhost) |
| A user sees no connections | No data access policy on their roles allows a connection | Attach a policy with an allow rule scoped to the connection — see Data access rules |
| Query blocked: no matching rule | No allow rule matches the table, or a higher-priority deny does | Adjust the policy's rules and priorities |
| "Reading system.query_log needs the permission 'query:history:view:all'" | The table shows other people's statements, or ClickHouse users and grants | Give the role query:history:view:all (statement logs) or clickhouse:users:view (access tables) — see Data access rules |
"This statement would change data or settings, and it was sent read-only" (READ_ONLY) | ClickHouse refused a write on a read-only request: your roles hold no write permission, or the feature (a dashboard panel, a scheduled query, a notebook cell) only reads | Run the write from the SQL editor with a role that may write — see Reads are sent read-only |
| "This connection's ClickHouse user is read-only and refused the setting …" | The connection's ClickHouse login has readonly = 1, which refuses the settings CHouse UI sends with every request | Have a ClickHouse administrator set readonly = 2 for that login, which still refuses every write |
"This connection's ClickHouse user isn't allowed to do this" (CLICKHOUSE_ACCESS_DENIED) | ClickHouse itself refused: the connection's login lacks a grant. The message names it | Grant it in ClickHouse; Test in Admin › Connections lists what each feature needs |
"ClickHouse refused this connection's login" (CONNECTION_AUTH_FAILED) | The connection's stored username or password is no longer accepted by ClickHouse | Update them in Admin › Connections |
"Your role has no ClickHouse role on this connection yet" (IDENTITY_UNAVAILABLE) | The connection limits people to a ClickHouse role and your CHouse role is not in its role map, or the mapped role does not exist in ClickHouse | A super admin maps the role in Admin › Connections › ClickHouse login — see Connection kinds |
"Your account is not linked to a ClickHouse user on this connection", or the link is waiting, suspended or disabled (IDENTITY_UNAVAILABLE) | The connection is personal and your account has no active link | A super admin creates or confirms the link in Admin › Connections › Linked ClickHouse users — see Link an account to a ClickHouse user |
| "SET runs in a session…", "An INSERT that carries its rows…", or "…If it ends with a FORMAT clause, remove the clause" | On a personal connection every statement is one request sent as your ClickHouse user | Put settings in the statement's SETTINGS clause, qualify table names, import rows as a file, and leave out FORMAT |
A kind is greyed out in ClickHouse login with "Not available on this server", or a switch answers KIND_UNSUPPORTED_ON_SERVER | The ClickHouse server cannot run that kind: the role ceiling needs 24.4 or newer, a personal connection needs EXECUTE AS | Upgrade ClickHouse, or use a kind the server can run — see Which kinds a server can run |
"This connection is not available" (CONNECTION_UNAVAILABLE) | A role-ceiling or personal connection failed its checks, or has not been checked for 15 minutes. The message gives the reason | Fix what the message names in ClickHouse, then Check now in the connection's Identity panel |
| A scheduled query fails with "This job has no owner" | The job has no account to run as | Open the job and choose Assign to me, or save a change to it — see Who a job runs as |
DDL refused with SCHEMA_PREFLIGHT_BREAKS | The change would break a dependent view, job, promise or saved query | Follow the safer plan shown, or have someone with schema:override confirm — see schema preflight |
| Results cut off | Your result row limit | Raise Max result rows in Preferences or add LIMIT |
| Stored connections can't be decrypted after a restart | RBAC_ENCRYPTION_KEY or RBAC_ENCRYPTION_SALT changed | Restore the original values; re-enter passwords if they are lost |
Data, monitoring & fleet
| Symptom | Cause | Fix |
|---|---|---|
| A Monitoring tab or Data tab is missing | Permission not granted | Check Preferences › Identity & access and the permission catalog |
| Data shows "No tables observed yet" or unsupported features | The collector's first pass hasn't finished, or the connection user lacks system-table grants | Admin › Connections › Edit › Test connection and run the listed GRANTs — see ClickHouse privileges |
| Empty query logs | query_log disabled or not flushed yet, or no grant on system.query_log | Enable query logging; wait for the first flush; grant read access |
| Fleet shows Snapshot worker stalled | No fresh samples | Check server logs for collector errors and the connection's grants — see Fleet |
| Fixes approved but never run | No remediation credential on the connection, outside the maintenance window, or the target changed since approval | Add the credential; wait for the window; re-propose — see fixes |
| Codec trials fail | The connection user can't write to OBSERVE_SCRATCH_DATABASE | Create the database and grant write access on it |
AI, alerts & agents
| Symptom | Cause | Fix |
|---|---|---|
| AI buttons missing for everyone | No active AI deployment | Add a provider, model and deployment in AI models |
| AI buttons missing for one user | No ai:optimize / ai:chat | Grant them through a role |
| No alert delivered | Channel misconfigured or disabled | Send test on the channel in Alerting |
| Doctor scheduled scan didn't run | Schedule disabled, or no AI model | Check Scheduled scans on the Doctor page |
MCP returns 404 MCP_DISABLED | The endpoint is off (the default) | Turn it on in AI Governance › MCP — see MCP |
MCP returns 403 ORIGIN_NOT_ALLOWED | The client sends an Origin that isn't allowed | Add the origin in AI Governance › MCP, or use a client that sends none |
MCP or CLI returns 401 | Token revoked, expired or mistyped | Create a new token |
| An agent can't see a tool | The tool is off, or the token lacks its permission | Check the tool in AI Governance › MCP and the tool catalog |
| Agent queries blocked | A budget policy, or agent access is paused | See AI Governance › Policies — see AI Governance |
Start-up & upgrades
| Symptom | Cause | Fix |
|---|---|---|
| Refuses to start in production | JWT_SECRET, RBAC_ENCRYPTION_KEY or RBAC_ENCRYPTION_SALT missing or the wrong length | Generate them as in Secrets |
| Logs an error about the scheduler and HA | SQLite with CHOUSE_HA=true | Use PostgreSQL for more than one replica |
Warning about MCP_* or FLEET_POLLER_ENABLED | Settings removed or deprecated in 3.14 | Remove them. MCP is now turned on and configured in AI Governance › MCP — see MCP; fleet collection always runs, and FLEET_POLL_INTERVAL_SECONDS still sets its interval |
| Migration fails on upgrade | Unexpected database state | Restore the backup, run the previous version, and open an issue with the log |
Collect diagnostics
bash
docker logs -f chouse-ui # server logs (JSON)
docker logs chouse-ui 2>&1 | grep RBAC # migrations and seeding
curl -s http://localhost:5521/api/health # liveness
chouse status --debug # server version, CLI compatibility, request idsStill stuck? Open an issue with the log excerpt, the request id from the error and the steps to reproduce.