---
title: "Troubleshoot by Symptom"
url: "https://docs.caracal.run/v1.0/operations/troubleshooting/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/operations/troubleshooting.md"
description: "Triage an application-visible failure and route it to authorization, configuration, or infrastructure diagnosis."
page_type: "workflow"
concepts: []
requires: []
---

# Troubleshoot by Symptom

Canonical URL: https://docs.caracal.run/v1.0/operations/troubleshooting/
Markdown URL: https://docs.caracal.run/markdown/v1.0/operations/troubleshooting.md
Description: Triage an application-visible failure and route it to authorization, configuration, or infrastructure diagnosis.
Page type: workflow
Concepts: none
Requires: none

---

Use this when an SDK, HTTP request, console action, or protected call failed. It identifies the failed surface; it does not repair infrastructure.

## Prerequisites

Capture timestamp, request ID, zone, application, resource, operation, status, error code, and version. Redact credentials.

## Triage Procedure

1. Check readiness. If any service is NotReady, use [Debug Infrastructure Issues](/v1.0/operations/debugging/).
2. For client startup failure, verify explicit profile, endpoints, IDs, and credential file.
3. For `401`, verify credential type, issuer, expiry, and intended surface.
4. For STS `403`, inspect Grants, Resource/scopes, Policy set, Session, Delegation, and Approval.
5. For resource/Gateway `403`, verify mandate issuer, audience, scope, `X-Caracal-Resource`, binding, revocation, and verifier.
6. Search Audit by request ID. If absent, confirm the request reached enforcement, then inspect the audit path.

## Verification

Repeat one safe request and confirm its expected status and audit Subject/resource/scopes/policy/result.

## Recovery Boundary

Do not widen policy, bypass Gateway, disable revocation, or replace credentials until the surface is identified.

## Diagnostic Bundle

Caracal exposes diagnosis through existing supported surfaces rather than a separate `doctor` command:

| Evidence | Surface |
| --- | --- |
| Runtime health and readiness | `caracal status --json` and `caracal status --ready --json` |
| Service, Zone, and provider checks | Web console **Diagnostics** |
| Recent decisions and operational events | Web console **Audit** or the Admin API audit list |
| One correlated authorization path | Request trace by request ID |

Capture those outputs with the timestamp, version, Zone, and request ID. Redact credentials before attaching the bundle to an incident.

## Next Step

Use [Debug Infrastructure Issues](/v1.0/operations/debugging/) or [Debug Authorization Decisions](/v1.0/guides/authorize-access/).