# Troubleshooting

## Start with the correct error layer

Check HTTP status, JSON-RPC `error`, tool `isError`, then returned business status. HTTP 200 alone does not mean a tool succeeded. Record the provider/client version, tool name, UTC time, request ID when available and sanitized error text. Never include Authorization headers, refresh tokens, signed URLs, private files or record datasets.

## Connection fails

- 401: verify the correct environment, bearer credential, connection expiry/revocation and the issuer's current owner/admin role. A browser login does not authenticate MCP.
- OAuth access expired: refresh once through the client's coordinated refresh flow, or link again if the grant expired/revoked.
- Refresh reuse: the family was revoked; link again. Do not replay old refresh credentials.
- 403: inspect organization enabled state and approved actual client registration IDs. A manual token is blocked when approved OAuth clients are required.
- 405: POST to `/api/mcp`, not GET/SSE, a public docs route or the login page.
- Invalid registration/code: verify registered redirect URI, S256 verifier, resource/issuer binding and client authentication. Do not weaken validation to make linking work.

## Missing or denied tool

Inspect authenticated `tools/list`, not just the public catalogue. Check original modules/read-write grant, current narrowing modules/actions, allowlist and denylist. New tools/modules do not silently expand old grants.

For outcome helpers check both helper permission and all composed read-tool/module permissions. Tools that remain advertised can still deny execution due to record scopes, sharing settings or quotas.

Unsupported record scopes intentionally deny. Ask an administrator for an appropriate narrow connection or use the app; never clear restrictions automatically.

## Document, export or mask surprises

Documents require both organization and connection permission. Masks apply to JSON fields, not attachment contents. Larger raw files must be downloaded in the application.

Arrays above 100 entries require both export grants. Row and byte caps apply even with export permission. Narrow the query; do not assume a rejected/limited report is complete. Scoped lists may have empty pages and omit global totals.

## Approval is pending, rejected or expired

A pending approval made no business change. A human must review in Settings → MCP → Approvals; provider OAuth consent is not that review. Approval does not execute the action.

Use the same connection to inspect and execute the stored approval. Policy changes reject pending/approved requests. Used, rejected or expired requests cannot be reused. The configured MCP rule can allow an ordinary/sensitive edit without extra review, but existing business approval requirements remain.

## Mutation outcome is uncertain

Do not automatically retry. Check application records and activity. An `executing` or failed request may have an uncertain committed outcome; it cannot be reclaimed automatically. A `completed` response with withheld details means the write succeeded but sharing policy suppressed the detailed output.

## Quota failure

Transport request/concurrency failures may be 429 with Retry-After; tool change/download failures can be `isError`. Inspect organization, user and connection budgets, not just IP limits. Fixed-window request counters reset each minute; change/download counters each hour. Concurrency leases expire if the process disappears and are renewed during a running operation.

Never retry an uncertain write just because a quota error followed it. Read-only retries should be bounded and honor server guidance.

## Native view is absent or a panel fails

Check whether the actual host supports MCP Apps and `_meta.ui.resourceUri`. Structured/text fallback remains usable. Check selected location UUID, workflow modules, composed read tools, document/export settings, row/byte limits and warnings. A failed panel is not zero activity, and unknown actual costs are not zero cost.

## Publish migration reports an existing relation

Compare current development and read-only production catalogues, then recompute the development-to-production diff. A previously generated create plan may be stale relative to the validation target. Check for competing schema writers; production and publish-test startup should only assert schema read-only.

If the fresh diff is empty, no database repair is needed: retry the normal Publish flow. If it is destructive, investigate and obtain approval before changing development structures. Never fix this by dropping production tables or adding deployment DDL.