Troubleshooting

Never paste a token, password, signed URL, catalog credential, or authorization header into chat, screenshots, or support messages.

Dashboard does not open

• Run docker compose ps from MigrationRoom and wait for the dashboard, runner, chat, Databricks MCP, and ClickHouse tooling to become healthy.
• For the local self-signed certificate, bypass the warning only when the address is exactly https://localhost.
• If chat remains blank, refresh once, then select New conversation and confirm the header says Databricks → ClickHouse Cloud.

Source database does not appear

The picker is populated through the source connector. Confirm the .env values and that the read-only identity has USE CATALOG, USE SCHEMA, and SELECT. If the UI falls back to a text field, enter migration_demo.tpch, but treat that only as a navigation fallback—not proof that credentials work.

A step card does nothing

Wait for the chat iframe to finish loading and make sure no other step is still busy. Re-select the intended conversation, then click the card once. If an error appears under the cards, preserve it and resolve the named prompt/authentication problem rather than pasting the prompt manually into a different agent.

Discovery uses the wrong tool

Step 1 should call list_tables, run_select_query, and describe_table through databricks-source. If it tries unrestricted Python for source discovery, stop it in chat and require the Databricks MCP tools. Missing counts or Delta detail should be retrieved in the same conversation before DDL approval.

Migration appears quiet

Quiet chat is normal after the background migrationkit job starts. Select the active run and inspect the Migration view. Do not click Migrate Data repeatedly. If there are duplicate runs, choose one authoritative run and cancel the others without deleting their failure information.

Validation differs

Do not repair target rows manually. Ask the agent to check source snapshot timing, failed batches, schema order, nullable transforms, and deletion-vector changes. Repair the cause, re-fire Migrate Data, then Validate against the same intended dataset.

Benchmark looks implausible

Check correctness first, then cold/warm state, Databricks server time versus wall time, query pairing, service size, and omitted failures. Re-run the complete UI benchmark under declared conditions; do not retain only the fastest observation.

Catalog query fails

Ask the instructor to verify the pre-attached unity_tpch and rest_catalog_tpch databases. Metadata visibility, catalog credential vending, object-store access, and network reachability are separate failure points. Never ask the agent to print the secret-bearing attachment DDL.

Optimization regresses

Keep the before/after Benchmark views. Ask the agent to verify the optimized query used the dictionary, materialized view, or projection and that result semantics match. If the measured benefit does not justify the complexity, use the approved rollback and record that decision.