Troubleshooting
Probes
Section titled “Probes”Every service answers two probes, to any host name and without a key:
/health: 200{"status": "ok"}while the process runs./ready: 200 when it can serve. The API and a worker are ready when their storage is writable and PostgreSQL answers with the schema they expect; the editor when the API is ready. Otherwise 503, with what failed:
{ "ready": false, "checks": { "storage": "ok", "database": "ECONNREFUSED" } }The Compose file uses /ready as each service’s health check. docker compose ps shows which are healthy.
Every service logs to its standard output and error: docker compose logs api, or worker, or editor. PAPRIKA_LOG sets how much:
PAPRIKA_LOG |
Logs |
|---|---|
all |
Every request, warnings, and each job a worker claims |
errors |
Failed requests and warnings only |
off |
Nothing |
A request’s line has its time, request id, method, path, status, duration, size and tenant, and when it failed, the error’s code and message. An unexpected failure adds its stack trace after the line.
Request ids
Section titled “Request ids”Every answer carries its request id, in the X-Request-Id header and, for an error, in requestId. When a tenant reports a problem, ask for it: it finds the request’s line in the log. Unexpected failures answer only internal-error and the id; what went wrong is in the log.
Common answers
Section titled “Common answers”| Answer | Means |
|---|---|
401 unauthorized |
No key, or one that is wrong, revoked, expired, or of a suspended or deleted tenant |
401 admin-unauthorized |
The admin API without a token from PAPRIKA_ADMIN_TOKEN, or with none set |
403 scope-missing |
The key hasn’t the scope the request needs |
429 rate-limited |
The tenant is past its tier’s ratePerMinute (scheduler) |
429 queue-full |
The tenant has PAPRIKA_MAX_QUEUED_JOBS jobs queued or running |
503 busy |
The API’s render threads are all taken: add API replicas or raise PAPRIKA_WORKERS |
503 on /ready |
Storage or the database is unavailable, or the schema is behind: run migrate |
The editor
Section titled “The editor”A designer whose editor misbehaves can open it with ?debug at the end of its address: it shows the drawing times in a corner. A page that can’t be drawn says so once and keeps its last picture; an unexpected error is told once in a message, however often it happens. The editor shows when it can’t reach the server, and notices within seconds when it can again.