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 ps -a and the migrate, assets, web and gateway logs. Check initialization, port or origin configuration. The development and release profiles use different service names for the public gateway.

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 429 responses, distinguish gateway rate limits from the application login lockout. Check the trusted hop count when a proxy or CDN sits in front of Caddy.

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.

ContextBase0.1.0

Search the documentation