Doctor and health checks
pi-durable-platform doctor, the /healthz and /readyz probes, logs and request IDs, and common start-up problems.
doctor
pi-durable-platform doctor checks an install without changing anything, using the same configuration as serve:
- Configuration: loads it and validates it for
serve(or--mode migrate). - Safety: the production safety checks.
- PostgreSQL: connects to the platform database and reports its version and the time it took.
- Migrations: whether the database is at the binary's migration.
- Keys: during an
API_KEY_PEPPERrotation, how many keys are still on the previous pepper. - Agents database (since v0.1.1): connects to
AGENTS_DATABASE_URLand checks that its role can provision agents. It reads the role's attributes and privileges and creates nothing.
The agents database checks
| Check | OK when | Otherwise |
|---|---|---|
agents database | The database answers; reports its PostgreSQL version, the database and the role | Fail, with the connection error (never the URL or its password). If the database doesn't exist yet and AGENTS_CREATE_DATABASE=true, it's info: serve creates it. |
agents provisioning | PostgreSQL 16 or later, and the role has CREATEROLE and CREATE on the database (or is a superuser) | Fail, naming what's missing, with the fix: ALTER ROLE <role> CREATEROLE; GRANT CREATE ON DATABASE <db> TO <role> (or make the role the database's owner), or move to PostgreSQL 16 or later |
Each agent gets its own role and schema in the agents database, which is why the platform's role needs CREATEROLE and CREATE; PostgreSQL 16 is the first version that lets it grant itself membership of each agent role the way provisioning does. See Databases.
Without AGENTS_DATABASE_URL the checks are skipped, reported as info ("agents can't be deployed"): the configuration checks already say whether your launcher needs it.
pi-durable-platform doctor # text report
pi-durable-platform doctor --json # for scripts
pi-durable-platform doctor --timeout 20sIt exits 1 if any check fails, with a fix for each failure. The image has no shell; on Kubernetes run:
kubectl -n pi-durable-platform exec deploy/pi-durable-platform -- /pi-durable-platform doctordoctor doesn't check the Kubernetes API or the identity provider: deploying and testing an agent covers them. The readiness probe also checks that the agents database answers.
Probes
| Path | Answers |
|---|---|
GET /healthz | Liveness: the process is up |
GET /readyz | Readiness: both databases answer and the platform isn't shutting down |
On SIGTERM /readyz fails first, for SHUTDOWN_DELAY, so load balancers stop sending traffic before the server stops.
Logs
The platform logs to standard output, as JSON by default (LOG_FORMAT, LOG_LEVEL). Every response carries an X-Request-ID header; the same ID is in the logs and in audit entries, so you can follow one request. Secrets, keys and tokens are never logged.
v0.1.1 has no metrics endpoint; metrics and tracing are planned for v0.2 on the roadmap.
Common problems
| Symptom | Cause |
|---|---|
| Refuses to start: "the database is at migration N but this binary needs M" | Run migrate, or set MIGRATE_ON_START=true |
Refuses to start naming DEV_AUTH, AGENTS_LAUNCHER=local, an example key or an http APP_URL | A production safety check: see Configuration |
| "agents database not ready; retrying" in the logs | The platform waits for the agents database at start-up; check AGENTS_DATABASE_URL and the network, and run doctor |
| Deploying an agent fails with a permission error on the agents database | The platform's role lacks CREATEROLE or CREATE on the database, or the server is older than PostgreSQL 16: doctor's agents provisioning check says which |
Agents answer 503 agent_unavailable | The runtime didn't start in time: check the agent pod's events and logs, the image, AGENTS_IMAGE_PULL_SECRET, quotas |
| Agents start but every reply fails | Agents can't reach AGENTS_GATEWAY_URL (the gateway listens on 127.0.0.1 by default), or the model's provider refuses: see the thread's last error |
| Everyone is refused at sign-in with "A verified email address is required" | Your provider doesn't send email_verified: see OIDC sign-in |