Troubleshooting

A service is unhealthy

docker compose ps
docker compose logs --no-color api worker postgres redis typesense web
curl -fsS http://localhost:3001/api/v1/health/live
curl -fsS http://localhost:3001/api/v1/health/ready

Liveness confirms the API process. Readiness also checks required dependencies.

Login or setup fails

Confirm APP_ORIGIN, cookie security, browser origin, setup state, and rate-limit timing. Do not weaken cookie/TLS settings to work around a reverse-proxy error.

A source test fails

Check DNS from the API container, TLS policy, destination safety settings, account privileges, and PostgreSQL's read-only default. Indexlume intentionally rejects private/insecure targets unless explicitly allowed.

An indexing job fails

Open Indexing Jobs, select the run, and inspect recorded errors and counts. Correct the source/mapping problem, then retry supported failures. Do not delete job rows or manually edit checkpoints.

Search returns no results

Confirm the collection has an active generation, the indexing job completed, the project/slug is correct, and the requested fields are mapped. Test the same query in Search Studio before debugging the client.

Restore is rejected

Do not bypass the guard. Verify checksums, Compose project confirmation, archive completeness, pinned versions, and the original encryption key.