> ## Documentation Index
> Fetch the complete documentation index at: https://keyring.docs.composio.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Health and troubleshooting

> Verify Keyring and diagnose network, authentication, policy, KMS, and audit failures.

Start with the public health checks, then use the Keyring request ID and protected logs to identify the
failing boundary. Customers do not need to call Keyring's authenticated application endpoints directly.

## Verify the public path

Run these checks through the same HTTPS hostname, load balancer, and firewall path that Composio uses:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail https://keyring.example.com/healthz
curl --fail https://keyring.example.com/readyz
curl --fail https://keyring.example.com/transfer-keys
```

| Check            | What success confirms                                                      |
| ---------------- | -------------------------------------------------------------------------- |
| `/healthz`       | The Keyring process is running and can serve requests                      |
| `/readyz`        | The local process completed startup; this is not a full dependency probe   |
| `/transfer-keys` | Keyring can read the configured public transfer key from your KMS or Vault |

If the checks work from your network but not from Composio, review the public DNS, certificate, edge
source allowlist, and [Composio egress addresses](/deployment/overview#network-access).

## Check Composio authentication

If Composio receives `401`, compare these values first:

| Setting         | Expected production value                                   |
| --------------- | ----------------------------------------------------------- |
| `AUTH_ISSUER`   | `https://backend.composio.dev`                              |
| `AUTH_JWKS_URL` | `https://backend.composio.dev/.well-known/jwks.json`        |
| `AUTH_AUDIENCE` | Organization ID from Dashboard → Project Settings → General |

A project ID beginning with `pr_` is not a valid `AUTH_AUDIENCE`. Keyring authenticates the Composio
organization; project connection is configured separately.

## Common failures

<AccordionGroup>
  <Accordion title="Keyring does not start">
    **Likely cause:** a required environment variable is missing, the encryption configuration is
    invalid, production URLs are not HTTPS, KMS identity cannot initialize, or required auditing has
    no collector URL.

    **Fix:** compare the deployment against [Runtime configuration](/configuration/runtime) and
    [Encryption configuration](/configuration/encryption). Startup logs name the invalid field without
    printing its secret value.
  </Accordion>

  <Accordion title="Transfer-key check returns 500">
    **Likely cause:** the asymmetric key is missing, disabled, unreachable, uses the wrong RSA OAEP
    algorithm, or the Keyring workload lacks public-key access.

    **Fix:** confirm the configured transfer-key version, provider permissions, and RSA OAEP SHA-256
    properties.
  </Accordion>

  <Accordion title="Composio receives 403">
    **Likely cause:** the toolkit, destination, token operation, redirect, secret placement, key, or
    environment is denied by policy.

    **Fix:** use the request ID to find the warning event. Correct a toolkit or destination mismatch;
    do not broaden the provider allowlist before understanding the denial.
  </Accordion>

  <Accordion title="KMS or Vault operations fail">
    **Likely cause:** workload identity is missing, the exact key permission is absent, a key is disabled,
    or the configuration references an old key.

    **Fix:** verify the ECS task role, Cloud Run service identity, Kubernetes workload identity, or Vault
    auth role. Keep historical keys configured until every stored credential has been migrated.
  </Accordion>

  <Accordion title="Sensitive operations fail when the collector is unavailable">
    **Likely cause:** `AUDIT_DURABILITY=required` is working as designed and your collector did not
    acknowledge the audit event.

    **Fix:** restore collector network, authentication, and ingestion health. Switch to `best_effort`
    only after an authorized owner accepts the loss of the audit gate.
  </Accordion>
</AccordionGroup>

## Status codes in Keyring logs

| Status | Boundary                | Typical meaning                                                  |
| -----: | ----------------------- | ---------------------------------------------------------------- |
|  `400` | Request validation      | The signed request or encrypted credential was malformed         |
|  `401` | Authentication          | The Composio token was missing, expired, or did not match config |
|  `403` | Policy or KMS allowlist | The toolkit, destination, operation, or key was not allowed      |
|  `413` | Buffered payload        | A structured request exceeded the Keyring processing limit       |
|  `500` | Configuration/safety    | Keyring stopped rather than continue with an unsafe state        |
|  `502` | External dependency     | KMS, Vault, or the provider returned a failure                   |
|  `503` | Signing-key dependency  | Composio signing keys were temporarily unavailable               |

A provider can return its own non-success status. Use the Keyring request ID and event source to
distinguish a provider response from a Keyring denial.

## Safe diagnostics

Collect only:

* Keyring request ID and timestamp;
* HTTP status and safe error tag;
* deployment environment and release/image tag;
* toolkit and provider hostname; and
* relevant KMS key identifier, workload role, or audit collector status.

Never paste authorization headers, signed JWTs, sealed browser payloads, encrypted credential data,
decrypted provider responses, environment dumps, or collector credentials into tickets or chat.

After the issue is resolved, confirm that the corresponding customer audit event records the tool call
or OAuth operation and its final outcome.