# Troubleshooting

Common issues when working with ZeroID tokens, delegation, and self-hosted deployments.

***

### Token Verification Failures

**`tokens.verify()` raises an exception**

* Verify the JWKS endpoint is reachable from the verifying service.
* Check that the token has not expired (`exp` claim).
* Ensure the token's `iss` (issuer) matches your ZeroID instance URL.
* For delegation tokens, verify the `act.sub` chain is valid.

**`tokens.verify_bearer()` raises**

* Check that the `Authorization` header value starts with `Bearer` (note the space).
* The header value should be `Bearer <token>`, not just `<token>`.

***

### Delegation Failures

**`tokens.delegate()` returns an error**

* Verify the `actor_token` is a valid, unexpired access token.
* Check that delegation is allowed by the credential policy for this identity.
* Check `max_delegation_depth` — if the subject token is already at the maximum depth, further delegation is blocked by policy.

***

### Self-Hosted Deployment Issues

**Service health check fails**

```bash
curl http://localhost:8899/health
```

Expected: `{"status": "healthy", "service": "zeroid"}`

If this fails:

* Check that the Docker containers are running: `docker compose ps`
* Check logs: `docker compose logs zeroid`
* Verify the database is reachable: `docker compose logs postgres`
* Verify signing keys were generated: `ls ./keys/`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/agent-identity-zeroid/guides/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.