Troubleshooting
Operate
Troubleshooting
Section titled “Troubleshooting”Troubleshooting starts from symptoms, scope, reason codes, and metadata-only evidence. The goal is to prove or restore the governed MCP path without bypassing policy, reading production databases, or exposing private payloads.
Audience
Section titled “Audience”- Operators diagnosing failed runtime checks.
- Security operators reviewing denials or no-secret scan failures.
- Support engineers turning request IDs into safe remediation.
- Docs reviewers checking public troubleshooting material.
What is this?
Section titled “What is this?”This page is the public symptom matrix for V1. It routes identity, policy, credential, connector, API import, SIEM/export, session drain, and secret-scan failures to concrete checks and fail-closed action.
When do I use it?
Section titled “When do I use it?”Use it after the Operator Workflow baseline when one surface still fails. If the question is “why did the gateway hide or deny this tool?”, include Audit and Deny Diagnostics in the path.
What happens?
Section titled “What happens?”- Capture branch, exact command, exit status, request ID when available, and first failing check.
- Map the symptom to the contract or runbook surface that owns the reason code.
- Use Admin API, CLI, harness, or audit search instead of direct database inspection.
- Preserve deny, disabled, revoked, or blocked state until the source-backed fix is known.
- Record safe resource IDs, redaction status, whether upstream was attempted, and the V1 boundary.
Symptom matrix
Section titled “Symptom matrix”| Symptom | Check | Fail-closed action |
|---|---|---|
| Docs missing or stale | docs harness | Link the missing source and keep the page draft until source exists. |
| Identity missing | identity/policy/revocation eval or /v1/identity/me source flow | Deny discovery and calls until IdP or local identity refs validate. |
| Policy deny unclear | policy simulation plus deny diagnostics | Preserve deny and review Cedar version/context. |
| Credential unavailable | credential-binding status | Block new calls and rotate, reapprove, or revoke the binding. |
| Connector disabled | connector status and impact | Keep route unavailable until lifecycle and health are source-backed. |
| API import rejected | OpenAPI import diagnostics | Fix selection, approval, host allowlist, schema, timeout, size, or credential mapping before publish. |
| SIEM/export denied | audit export or telemetry/SIEM check | Preserve local audit metadata and fix customer export refs. |
| Session drain issue | reconnect/drain/terminate eval | Reject new stateful sessions and finish drain or rollback. |
| Secret scan failure | full harness or no-secret gate | Remove retained material and keep only metadata. |
What can go wrong?
Section titled “What can go wrong?”- The same failing command is rerun without changing inputs or reading the first failing check.
- A denial is “fixed” by weakening policy, broadening host allowlists, disabling schema checks, or bypassing credential binding state.
- Support packets include tokens, prompts, request bodies, response bodies, tool payloads, customer data, screenshots with secrets, or copied private payloads.
- A public page cites internal workpads or raw evidence instead of curated source docs.
- Troubleshooting introduces a non-V1 dependency to recover a path that should fail closed.
Source truth
Section titled “Source truth”- Read Operator Workflow for the baseline loop.
- Read Audit and Deny Diagnostics for request-level explanation.
- Read Security Review before turning a troubleshooting finding into public guidance.
Type set in Geist, Source Serif 4, and Departure Mono.