Troubleshooting Matrix¶

Use this page as a fast symptom-to-fix reference for local setup, development, and test execution.

Triage Flow¶

flowchart TD
    A[Observe symptom] --> B[Classify: setup, runtime, test]
    B --> C[Check service health and logs]
    C --> D[Verify env and configuration]
    D --> E[Run targeted validation command]
    E --> F[Apply fix and re-verify]

Common Issues¶

Symptom	Likely Cause	Validation Command	Suggested Fix
`docker compose` services do not start	Docker daemon not running or port conflict	`docker compose ps`	Start Docker, free conflicting ports, restart stack
App starts but HTTP requests fail	DB/Redis not healthy or env mismatch	`docker compose logs -f app db redis`	Fix `.env` credentials and service health issues
Migration command fails	Schema drift or invalid migration ordering	`docker compose run --rm app python manage.py showmigrations`	Reconcile branch migration history and rerun migrate
Tests fail during import/setup	Missing env vars or incompatible local state	`docker compose run --rm app sh -c "DJANGO_SETTINGS_MODULE=app.settings_test PYTHONPATH=. pytest --collect-only -q"`	Verify test settings and recreate local test state
Coverage threshold fails	New code lacks tests	`docker compose run --rm app sh -c "DJANGO_SETTINGS_MODULE=app.settings_test PYTHONPATH=. pytest --cov=app --cov-report=term-missing"`	Add focused tests for uncovered branches
Docs build fails	Broken links/nav or invalid markdown config	`docker compose run --rm app mkdocs build -f docs/mkdocs.yml`	Fix link targets or nav entries and rebuild

Where to Look First¶

Concern	First Command	Why
App startup	`docker compose logs -f app`	Captures Django boot and runtime errors
Database connectivity	`docker compose logs -f db`	Reveals readiness and auth issues
Worker tasks	`docker compose logs -f celery`	Shows async processing failures
Stack health	`docker compose ps`	Quick service state overview

Escalation Decision Guide¶

Situation	Immediate Action	Escalate?
Single user local issue	Reproduce with clean startup and check logs	Usually no
Reproducible module failure	Capture failing commands and logs	Yes, to module owner
Data integrity concern	Stop write operations and preserve evidence	Immediate escalation
Release-blocking regression	Open incident thread and assign owner	Immediate escalation

Fast baseline checks

Start with: docker compose ps, docker compose logs -f app, and docker compose run --rm app python manage.py check.

Collapsed escalation path

If issue persists after baseline checks, capture command output, recent changes, and affected module, then open an issue or ask for peer review with that context.