CHouseUI
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

SymptomCauseFix
Default login rejectedThe seeded admin is only created with a new RBAC database; its password may have been changedSign in as another admin and reset it in Admin › Users
"Password sign-in is disabled"AUTH_PASSWORD_LOGIN_ENABLED=false with a working SSO providerUse SSO, or set it back to true
Signed out after a deploy, or randomly with several replicasJWT_SECRET differs between pods or changedUse one fixed secret everywhere — see Sessions & JWT
SSO button missingAUTH_SSO_ENABLED is not true, or no valid providerSee SSO
SSO callback failsRedirect URI at the IdP ≠ <AUTH_SSO_BASE_URL>/auth/sso/callbackMake them identical
SSO change not visible on some podsPropagation intervalWait AUTH_CONFIG_WATCH_INTERVAL_MS (15 s by default)

Connections & queries

SymptomCauseFix
Connection refusedClickHouse isn't reachable from the server containerUse a host the server can reach (in Compose, the service name such as clickhouse-server:8123, not localhost)
A user sees no connectionsNo data access policy on their roles allows a connectionAttach a policy with an allow rule scoped to the connection — see Data access rules
Query blocked: no matching ruleNo allow rule matches the table, or a higher-priority deny doesAdjust 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 grantsGive 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 readsRun 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 requestHave 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 itGrant 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 ClickHouseUpdate 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 ClickHouseA 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 linkA 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 userPut 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_SERVERThe ClickHouse server cannot run that kind: the role ceiling needs 24.4 or newer, a personal connection needs EXECUTE ASUpgrade 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 reasonFix 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 asOpen the job and choose Assign to me, or save a change to it — see Who a job runs as
DDL refused with SCHEMA_PREFLIGHT_BREAKSThe change would break a dependent view, job, promise or saved queryFollow the safer plan shown, or have someone with schema:override confirm — see schema preflight
Results cut offYour result row limitRaise Max result rows in Preferences or add LIMIT
Stored connections can't be decrypted after a restartRBAC_ENCRYPTION_KEY or RBAC_ENCRYPTION_SALT changedRestore the original values; re-enter passwords if they are lost

Data, monitoring & fleet

SymptomCauseFix
A Monitoring tab or Data tab is missingPermission not grantedCheck Preferences › Identity & access and the permission catalog
Data shows "No tables observed yet" or unsupported featuresThe collector's first pass hasn't finished, or the connection user lacks system-table grantsAdmin › Connections › Edit › Test connection and run the listed GRANTs — see ClickHouse privileges
Empty query logsquery_log disabled or not flushed yet, or no grant on system.query_logEnable query logging; wait for the first flush; grant read access
Fleet shows Snapshot worker stalledNo fresh samplesCheck server logs for collector errors and the connection's grants — see Fleet
Fixes approved but never runNo remediation credential on the connection, outside the maintenance window, or the target changed since approvalAdd the credential; wait for the window; re-propose — see fixes
Codec trials failThe connection user can't write to OBSERVE_SCRATCH_DATABASECreate the database and grant write access on it

AI, alerts & agents

SymptomCauseFix
AI buttons missing for everyoneNo active AI deploymentAdd a provider, model and deployment in AI models
AI buttons missing for one userNo ai:optimize / ai:chatGrant them through a role
No alert deliveredChannel misconfigured or disabledSend test on the channel in Alerting
Doctor scheduled scan didn't runSchedule disabled, or no AI modelCheck Scheduled scans on the Doctor page
MCP returns 404 MCP_DISABLEDThe endpoint is off (the default)Turn it on in AI Governance › MCP — see MCP
MCP returns 403 ORIGIN_NOT_ALLOWEDThe client sends an Origin that isn't allowedAdd the origin in AI Governance › MCP, or use a client that sends none
MCP or CLI returns 401Token revoked, expired or mistypedCreate a new token
An agent can't see a toolThe tool is off, or the token lacks its permissionCheck the tool in AI Governance › MCP and the tool catalog
Agent queries blockedA budget policy, or agent access is pausedSee AI Governance › Policies — see AI Governance

Start-up & upgrades

SymptomCauseFix
Refuses to start in productionJWT_SECRET, RBAC_ENCRYPTION_KEY or RBAC_ENCRYPTION_SALT missing or the wrong lengthGenerate them as in Secrets
Logs an error about the scheduler and HASQLite with CHOUSE_HA=trueUse PostgreSQL for more than one replica
Warning about MCP_* or FLEET_POLLER_ENABLEDSettings removed or deprecated in 3.14Remove 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 upgradeUnexpected database stateRestore 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 ids

Still stuck? Open an issue with the log excerpt, the request id from the error and the steps to reproduce.

Edit this page on GitHub ↗