Guide baseline: Aelira Core v0.9.11
Troubleshooting
Identify the failing layer, preserve the original document, and collect only the diagnostics needed for support.
Start with read-only checks
These commands assume the production file and default database user/name. If you changed POSTGRES_USER or POSTGRES_DB, substitute those values. For the isolated evaluation, use docker-compose.quickstart.yml instead. Run from the appropriate checkout.
docker compose -f docker-compose.prod.yml ps
curl --fail-with-body http://localhost:8000/live
curl --fail-with-body http://localhost:8000/ready
docker compose -f docker-compose.prod.yml exec postgres psql -U aelira -d aelira -c 'SELECT 1'
docker compose -f docker-compose.prod.yml exec redis redis-cli ping
docker compose -f docker-compose.prod.yml exec worker python -m src.jobs.healthcheck --mode readiness --json
docker compose -f docker-compose.prod.yml logs --tail=50 api worker
docker stats --no-stream/live proves only that the API process can respond; /ready checks its database and Redis dependencies. Worker readiness is a separate check. Review logs locally before sharing them.
If you deliberately enabled Ollama, list installed models from inside its service; the production file does not expose a host port for it.
docker compose -f docker-compose.prod.yml --profile ollama exec ollama ollama listCommon symptoms
No dashboard in the evaluation stack
docker-compose.quickstart.yml does not define a dashboard. Use the full production stack for a dashboard on localhost port 8080, or follow source-development instructions for the Vite dashboard. Restarting a service is not rebuilding it.
A scan remains processing
Check the worker health state and recent worker logs. The API queues work but does not consume jobs. Confirm API and worker share the same release, database, provider settings and upload volume. Pause intake before recovery; do not edit queue rows or claim tokens by hand.
A local scan fails with job_handler_exception
This is a generic worker failure code, not a diagnosis by itself. In v0.9.11, missing TOKEN_ENCRYPTION_KEY prevents even local PDF jobs from running. Confirm a valid persistent Fernet key is present without printing its value. Quickstart requires an explicit entry in the shared API/worker environment mapping; a shell export alone is insufficient. Production reads the key from .env. Follow the setup guide, recreate the affected services and retry with a synthetic file. Investigate other causes if the key is already correct.
Database or Redis is unavailable
Check the postgres and redis services and /ready. In production Compose, keep direct-host connection examples commented; the file supplies container addresses. Changing a database password setting does not automatically change the password in an existing database volume. Preserve data and use your database administration procedure.
AI descriptions are unavailable
Check the workspace administrator’s AI Provider Settings: its saved provider, model values and primary/fallback selection drive authenticated document, image and web AI. Process-level LLM_PROVIDER and LLM_FALLBACK_PROVIDER do not configure that workspace. EMBEDDING_PROVIDER is separate. For Ollama, enable its profile, confirm the selected models are installed, then test workspace provider readiness. A running model container alone does not authorize LMS AI processing.
An after-score or PDF preview is unavailable
Open the review record diagnostics. A comparable score needs supported verification and matched original and saved bytes. Missing original files, unsupported structure or a legacy record must remain explicit. Rescan the retained original; upload it again if it is unavailable. Do not replace a missing score with an estimate.
Output is withheld or a download is blocked
Review manual, failed, unresolved and unreported outcomes. A generated candidate is not necessarily publishable. Check approval blockers and artifact expiry. Re-run remediation after resolving the source issue; do not force an approval or manually copy an unverified candidate into production.
OCR did not produce searchable text
Check the PDF findings and the documented per-page OCR boundary. Signed, XFA, partial-text and unsupported language cases may require manual work. Do not assume every image-based PDF is safe to rewrite, or that OCR creates a complete structure tree.
A web scan or media job times out
Check worker resources and job progress first. For an authorized website, reduce the requested page count and use a reachable URL; a protected LMS URL requires its configured integration. Keep the worker execution limit and stop grace period consistent. Do not install browsers ad hoc in a running production container.
A port or container name is already in use
Inspect the owning process or Docker service before stopping anything. Aelira Compose files use fixed container names. Choose an isolated test environment or adjust a deliberate local override, preserving private bind addresses. Stop a service gracefully only when you know what it serves.
LaTeX conversion fails
The convert API accepts an uploaded file, not inline JSON. Check the source syntax, supported packages and the returned conversion diagnostics. Compare the generated MathML and spoken representation against the original expression.
Authentication fails
Use a current API key with Authorization: Bearer for API examples. Browser sessions have separate cookie and CSRF requirements. Check public origins and trusted proxies. Legacy API keys revoked by a security migration must be reissued; never turn on mock authentication in production to work around a failure.
Recovery references
Use the release-specific worker recovery and backup guide. For output and scoring questions, see Scores and Review. For request formats and polling, see API Reference.
A safe support report
Include the release version, affected workflow, expected versus actual result, sanitized error code, service health summary and a synthetic reproducer where possible. Include only relevant configuration names and non-secret values needed for the diagnosis.
Do not paste .env files, full logs, student records, original customer documents, tokens, cookies, connection strings, signed links or private file paths into an issue. Redact identifying document and account details before sharing screenshots or diagnostic excerpts.
Report sanitized open-core bugs through GitHub Issues, or use Support to arrange an appropriate private channel.