Troubleshooting

This page is organized by symptom. Two distinctions do most of the diagnostic work: errors (the request failed — a typed code like unauthorized or query_parse_failed) versus answer states (the request succeeded and the typed answer reports what published state can support), and HTTP-layer failures (401/429/503 before any tool runs) versus tool-layer errors (returned inside the tool result). The full code table is at the bottom of this page.

Connection and authentication failures

Every invalid-token case — missing header, malformed header, mistyped token, unknown token, revoked token, expired token — returns the same unauthorized response (HTTP 401), by design. The response never says which case you hit, so work the checklist instead:

1. The Authorization header is Bearer followed by the token: Authorization: Bearer mtt_… — no quotes, no line breaks, nothing else in the value.
2. The token is intact: mtt_ followed by 64 hex characters. Truncation and stray whitespace are the most common copy-paste failures.
3. The token shows Active in the Tokens tab of your workspace's MCP module — not Revoked (revocation applies immediately to new requests) or Expired.
4. Token values cannot be retrieved after issue — only a hash is stored. If there is any doubt about what your client is sending, issue a fresh token from the Tokens tab (admin or owner role required) and re-register the client.

auth_unavailable (HTTP 503) is different: token verification infrastructure was temporarily unreachable, so your token was never judged. Retry shortly — do not reissue a token over a 503.

To separate network and URL problems from auth problems, hit the health check, which requires no token:

curl -sS https://<workspace-mcp-host>/health

If health fails, the problem is the endpoint URL or your network path, not the token. Your real endpoint is shown on the Connect tab; see Connect an agent.

Empty or "not enough published state" answers

not_enough_published_state is not an error — it is a successful, typed answer saying your workspace's published state cannot support a decision for that asset or scenario. Zero applicable published rows is reported this way on purpose: it is never an empty pass and never an invented decision. Each reason code names its own fix:

Reason code	What it means	Fix
no_current_publication	The workspace has no current deployment publication at all.	Publish a deployment — see Deployments.
no_published_instruction_state	A publication exists, but no published instruction rows apply to this asset and scenario.	Write a policy that targets the asset (or extend one to cover the scenario), then deploy and publish — see Policies.
unresolved_published_target	A published instruction targets something that could not be resolved in the catalog.	Review unresolved targets in Deployments, fix the target reference or catalog state, and republish.
scenario_unresolved	A free-text use could not be deterministically mapped to a canonical scenario.	Pass a canonical scenario_key explicitly, or align your workspace's scenario labels so the mapper can resolve your phrasing — see Scenarios.

Its sibling state review_required (reason codes decision_requires_review, conflicted_published_state) is likewise a governance outcome, not a malfunction: published rows exist but a human must decide. See Typed answer states for the full model.

Quota and rate limits

Every tool call — regardless of tool — consumes exactly one metered MCP call against your workspace's plan quota, checked before the tool does any work. Two distinct limits apply:

• rate_limited (HTTP 429): the per-token, per-minute request limit was hit. The response carries a Retry-After header; back off and retry. If one shared token serves many agents, issue separate tokens per agent.
• quota_exceeded (tool-layer): the workspace has used its MCP call quota for the current billing period. Calls resume next period, or on a higher plan — see Plans.

Metering never fails open: if the quota check itself cannot complete cleanly, the call is rejected (as read_failed) rather than allowed through unmetered.

Query validation errors

Both of these mean validate_query_context did not validate the query — treat them as gate failures, never as a pass:

• query_parse_failed: the SQL could not be parsed for governed-table extraction. Simplify the statement or split multi-statement input; validate the statement that actually reads governed tables.
• query_unresolved_identifier: a table identifier could not be fully qualified. Either use three-part names (database.schema.table) in the SQL, or pass default_database and default_schema in the tool input so one- and two-part names resolve.

asset_not_found

The referenced asset, column, or decision does not resolve in this workspace. Check, in order:

1. Spelling and normalization. Identifiers are lowercase normalized names — match what discover_context returns rather than what your SQL editor displays.
2. Catalog membership. The asset must exist in the workspace's synced catalog. asset_not_found is about resolution, not governance: an asset that resolves but has no published rows returns not_enough_published_state instead.
3. The token's workspace. The endpoint is shared; your token selects the workspace. A token from workspace A asking about workspace B's assets gets asset_not_found — cross-workspace references are indistinguishable from not-found, by design. Confirm the token was issued in the workspace you think you are querying.

Claude Code plugin issues

The plugin supplies slash commands and workflows; the MCP connection is registered separately with your token. So if /metatate: commands exist but tool calls fail with unauthorized, the plugin is fine — the registration or token is the problem.

• Check the connection from Claude Code with /mcp — the metatate server should show as connected.
• If the token was revoked, expired, or mistyped at registration, issue a fresh one (Tokens tab), then re-register: claude mcp remove metatate, then re-run the bundled helper. With --run it reads the token from the METATATE_MCP_TOKEN environment variable or prompts with input hidden, and it accepts the base URL or the full /mcp endpoint:

export METATATE_MCP_TOKEN=mtt_...
./plugins/metatate/bin/metatate-cloud-mcp-add \
  --url https://<workspace-mcp-host> \
  --config-scope user \
  --run

• To refresh the plugin itself, run /plugin marketplace update metatate-claude-plugins, then update or reinstall the plugin. See the Claude Code plugin page for the full install flow.

Where to look in the app

• MCP page, Connect tab — the Metatate Runtime Status card shows whether the canonical seven-tool inventory is registered for your workspace and how many governed tables the current publication serves ("N/A" means the count could not be read or there is no current publication — a useful hint when answers come back as not_enough_published_state).
• MCP page, Tokens tab — each token's Active / Revoked / Expired status (admins and owners only).
• MCP page, Tools tab — reproduce a failing call. "Live endpoint" mode sends a real request to the deployed endpoint with your pasted token, the exact path your client uses. See MCP tools in the app.
• Activity — token issue and revoke events are recorded in the workspace activity log, which answers "who revoked the CI token, and when".

Error code reference

The server emits errors only from this closed set. Messages are fixed and redacted: they never echo your SQL, token material, or workspace identifiers.

Code	Layer	Meaning	What to do
unauthorized	HTTP 401	Invalid or missing token; all cases are indistinguishable.	Work the auth checklist; reissue if in doubt.
auth_unavailable	HTTP 503	Token verification was temporarily unavailable; not a token verdict.	Retry shortly.
rate_limited	HTTP 429	Per-token, per-minute limit exceeded.	Honor Retry-After; split tokens per agent.
quota_exceeded	Tool result	Workspace MCP call quota exhausted for the billing period.	Wait for the period reset or upgrade — Plans.
asset_not_found	Tool result	Asset, column, or decision not resolvable in this workspace (including cross-workspace references).	See asset_not_found.
invalid_parameters	Tool result	Input rejected by the tool schema, including a non-canonical scenario_key.	Fix the input against the tool reference.
not_supported	Tool result	An intentionally unsupported mode (for example explain_why with kind: "validation", or discover_context classification-fact filters).	Use a supported input mode.
query_parse_failed	Tool result	SQL could not be parsed; the query was not validated.	See Query validation errors.
query_unresolved_identifier	Tool result	A table identifier could not be fully qualified; the query was not validated.	Qualify the name or pass default_database / default_schema.
read_failed	Tool result	A read or infrastructure failure (redacted), including a metering check that did not complete cleanly.	Retry; contact support if persistent.
output_validation_failed	Tool result	The tool produced output that failed schema validation; no partial result is returned.	Retry; report if persistent.
internal_error	Tool result	An internal server error; already logged server-side.	Retry; report if persistent.