Query and MCP troubleshooting
Fix catalogue, SQL, truncation, timeout, search coverage, connection, and OAuth issues.
Relation or field not found
Refresh GET /v1/catalog or call list_sources, list_datasets, and describe_dataset. Use the returned logical relation and field names exactly. Physical file paths, provider object names, UI labels, and a schema revision that has not been accepted are not valid SQL identifiers.
Query rejected
Submit one read-only SELECT. Do not use DDL, DML, PRAGMA, extension loading, file functions, network functions, or multiple statements. Bind values through ? placeholders. Use identifiers only from trusted catalogue metadata. Add an explicit LIMIT, reduce selected columns, and confirm every referenced dataset is within the grant.
Result is truncated
truncated: true means the result hit an enforced row bound. Narrow by time or key, aggregate, or continue with deterministic keyset filters and explicit ORDER BY. Raising maxRows cannot exceed the strictest request, grant, Account, and platform bound. Do not claim a total from a truncated sample.
Query timeout or cancellation
Reduce scanned datasets, time range, joins, projected text, and output rows. A cancellation or timeout does not authorize a mutation and is not a reason to weaken grants. Preserve the receipt ID and correlation ID; inspect the query receipt to distinguish canceled, failed, and completed execution.
MCP cannot connect
Confirm the endpoint includes a valid account_id, uses Streamable HTTP, and targets the HTTPS deployment origin. A 401 is expected during OAuth discovery; the client must follow WWW-Authenticate rather than treating the first challenge as a permanent connection failure. For a static credential, verify the runtime actually expands the token environment variable.
MCP tool is missing or denied
Combined exposes exactly six read-only tools. Refresh the client tool list after reconnecting. 403 indicates missing Account or Source access; tool availability does not grant data capability. 404 can represent an invisible resource.
search_context misses expected text
The tool performs literal substring matching, not embeddings or semantic search. Inspect its coverage object. It searches at most 8 Sources, 24 datasets, 24 total fields, and 3 fields per dataset. Narrow scope or search skipped datasets explicitly. Use query_sql for exact field selection, joins, and structured predicates. Never describe incomplete coverage as an exhaustive search.
Large MCP output
Use lower limits, narrower projections, aggregates, and follow-up calls. Human-readable text can be a bounded preview while structuredContent contains the complete permitted typed result. Make sure the client reads structured output rather than scraping display text.