Troubleshooting

The stack will not start#

docker compose config --quiet
docker compose ps
docker compose logs --tail=60 postgres dashboard collector
docker system df

No space left on device: inspect Docker disk capacity and logs. This blocked local normal-volume verification. Do not prune unrelated volumes; expand Docker storage or remove only artifacts you own. A memory-backed database can verify ephemeral behavior, but cannot test persistence or archive restoration.

Authentication fails after changing .env: POSTGRES_PASSWORD initializes a new volume; it does not reset an existing role password. Restore matching settings or alter that role deliberately. Do not delete a data volume as a password-reset shortcut.

Port 8501 is occupied: stop your other review dashboard or change the dashboard host mapping in your own Compose copy. Host Python cannot resolve postgres: it is an internal Compose hostname. Host Python needs its own reachable database URL; the source does not auto-load .env and the supplied Compose file does not publish the database port.

Health is OK but the dashboard is empty#

curl -fsS http://127.0.0.1:8501/_stcore/health
docker compose exec -T postgres psql -U cita -d cita -c "
SELECT road,count(*),min(measurement_time),max(measurement_time)
FROM measurements GROUP BY road ORDER BY road;"

Expected: Health can return ok with no measurements. The fixture seeds A1 only; select A1 and an appropriate historical range. A new installation is not an evaluation-data restore.

For 2026 results, the restore step requires the archived dump. Without access, check the public aggregate.

Fetches fail or collection is unhealthy#

docker compose exec -T postgres psql -U cita -d cita -c "
SELECT feed_name,outcome,error_type,fetched_at
FROM feed_fetch_observations ORDER BY id DESC LIMIT 20;"
docker compose exec -T postgres psql -U cita -d cita -c "
SELECT id,status,started_at,finished_at
FROM collection_runs ORDER BY id DESC LIMIT 10;"
docker compose exec -T collector python -m collector.healthcheck

Expected: Failed observations stay visible. Health requires a recent success/partial run; the fixture helper does not create a run row. A partial run can pass the health-age check without every feed working.

The fetcher retries defined transient GET failures at most three times with backoff. It uses 10/30-second connect/read timeouts and TLS 1.2, following the documented July incident. Do not disable certificate validation to hide an error. Missing measurements cannot be recovered from an archive the source never supplied.

A snapshot was archived but parsing failed#

docker compose exec -T postgres psql -U cita -d cita -c "
SELECT id,feed_name,parse_status,parse_error_type,raw_file_path
FROM raw_feed_snapshots WHERE parse_status='failed'
ORDER BY id DESC LIMIT 10;"

After fixing a parser in your own source, rebuild and reprocess a small selected set:

docker compose build collector
docker compose run --rm collector python -m collector.reprocess \
  --feed trafficstatus_a1 --failed-only --limit 5

Expected: Output is Reprocessed: N; failed: M. Zero selected rows is not a repair. Inspect M: this CLI does not set a nonzero exit code for failed selected snapshots. Reprocessing writes projections.

File not found: paths in the snapshot registry are absolute; the matching raw archive must be mounted at /app/data/raw. A dump does not include that volume. Duplicate responses skip parsing, so polling the same bytes is not a retry of a failed parse.

Warnings, alerts, or means look wrong#

docker compose exec -T postgres psql -U cita -d cita -c "
SELECT feed_name,warning_code,count(*) FROM parser_warnings
GROUP BY feed_name,warning_code ORDER BY count(*) DESC;"

unsupported_crs: means geometry was not safely derived, not that a whole regulation or traffic measurement was discarded. No automatic alerts: persistence functions exist but sync is not wired into the main runtime. Empty alerts are not evidence of clear traffic.

Historical unassessed quality: live quality is calculated dynamically; stored historical fields are not versioned verdicts. Different A3 mean: check the fixed period, direction, positive-value filters, observation weights, corrected input hash, and final-only rounding. Current collection is not the archived sample.