Troubleshooting

First-run model downloads

Whisper Large and fairness jobs in particular can take 10–30+ minutes to become ready the first time they run, because the underlying model weights are pulled lazily on first use rather than baked into the image. This is expected, not a hang.

Avoid the wait during a demo or first analysis by pre-warming weights ahead of time — see Self-hosting → Pre-warm model weights.

Windows path and case-sensitivity

Dataset file paths are case-sensitive, even on Windows. Combined with Windows' path-length limits, a deep checkout path can produce confusing "file not found" errors that have nothing to do with the dataset itself.

Apple Silicon (MPS) under Docker Desktop

Docker Desktop cannot expose Apple's Metal (MPS) backend to a container — this is a Docker Desktop limitation, not an AudioLens bug. If you're on a Mac and want GPU acceleration, run the worker natively outside Docker instead:

cd Backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
STORAGE_LOCAL_ROOT=shared-storage ML_DEVICE=mps \
  celery -A app.core.celery_app:celery_app worker --queues=gpu-fast,gpu-large --concurrency=1

See Device selection for how ML_DEVICE=auto picks a backend.

NVIDIA GPU not detected

If the gpu compose profile comes up but jobs still run on CPU, confirm the driver is actually visible inside a container before suspecting compose or AudioLens itself:

1. 1
   Check the host driver version

   NVIDIA needs driver 555+. Anything older won't work with the CUDA base image AudioLens ships.

2. 2
   Confirm GPU passthrough with a throwaway container

   copy

   docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

   If this doesn't show your GPU, the problem is in your Docker/NVIDIA Container Toolkit setup, not in the AudioLens compose file.

3. 3
   Re-check the profile flags

   Make sure you booted with --profile gpu and scaled worker-model-local to 0, per Self-hosting — a leftover CPU-profile worker will happily pick up jobs and mask the GPU issue.

Redis full or 503 responses

Redis is configured with noeviction and a memory cap (REDIS_MAXMEMORY, default 1gb). Once it's full, writes start failing and the API can return 503s. Check /health (below) first — it reports Redis status directly. If Redis is the culprit, either raise REDIS_MAXMEMORY or clear stale data with docker compose down -v and a fresh start (this wipes job history and uploaded audio, not your source checkout).

Checking system health

GET /health

reports Redis (all three logical DBs used by the API — sessions/cache, job metadata, Celery), storage backend reachability, worker count, and queue depth in one response. This is the first thing to check when something feels wrong — before digging into container logs.

Finding stuck jobs

scripts/queue-status.sh -w

watches queue depth and per-job status continuously, so you can see whether a job is actually progressing or just sitting in a queue with no worker consuming it. If a queue is backed up with no matching worker running, re-check which containers you started against the queue routing table — gpu-fast/gpu-large jobs need worker-model-local or worker-gpu/worker-amd, and cpu jobs need worker-cpu.