Troubleshooting

Troubleshooting guide for ZeroID — token verification failures, delegation errors, and self-hosted deployment issues.

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

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/