Troubleshooting

Client Connectivity Failures On Startup

Athena can continue running when some configured clients fail to connect.

Check:

1. URI correctness and credential validity.
2. Network reachability from the gateway host.
3. TLS mode and provider-specific requirements.

Use:

• GET /health/cluster
• GET /admin/clients

Deferred and Admission Pressure

For backlog and pressure analysis:

• GET /gateway/deferred/{request_id}
• POST /gateway/deferred/{request_id}/requeue
• GET /admin/admission-events

Backup Tooling Problems

If backups fail early:

• verify ATHENA_PG_DUMP_PATH
• verify ATHENA_PG_RESTORE_PATH
• ensure PostgreSQL client binaries are installed on host

Documentation Contract Drift

When route docs look stale:

cd apps/docs
npm run openapi:generate
npm run openapi:verify-athena

The verifier should report full coverage for Athena operations.

Operation Links

• GET /health/cluster
• GET /admin/clients
• GET /gateway/deferred/:request_id
• POST /gateway/deferred/:request_id/requeue
• GET /admin/admission-events