On this page
Diagnose common failures¶
Check the failing layer¶
Check the gateway first. Use the actual address of your installation.
curl --fail 'http://localhost:13000/health/?format=json'
HTTP 200 confirms database, cache and original-file storage checks. Use the same Compose project and file order as startup when checking the services below.
Symptom |
First check |
|---|---|
Setup or web UI fails to start |
Inspect |
HTTP health responds, but search fails |
HTTP health checks database, cache and original-file storage. Check setup readiness and the space’s selected model and index separately. A cold local model may still need to download its weights. |
A PDF upload produces a format or extractor error |
Check whether the deployment uses local UTF-8 extraction or the HTTP extractor. Verify its address and credentials from both API and worker. Check the selected OCR profile and the upload size limits. |
A document lifecycle operation has no progress |
Inspect the domain operation first. Confirm Beat delivery, the consumer’s queue subscriptions and its active/reserved tasks before retrying. See Run and recover background work. |
Search works, but generation fails |
Check the selected provider/model, its outgoing route, response limits and local or remote readiness for the space. The search pipeline itself may still invoke models for configured steps. |
Browser login works intermittently |
Check TLS, exact frontend origins and the cookie policy. For
|
Pool waits rise after scaling |
Inspect PgBouncer client waits and PostgreSQL backends. Check that database maintenance uses the configured direct endpoint. Adjust concurrency and budgets together. |
For installer failures, read ~/.contextbase/install.log. Record the
Compose project, app revision and time of failure. For a support report,
include the sanitized error, steps to reproduce and readiness checks that
succeeded. Keep credentials and user documents out of the report. See the support guide.