Troubleshooting#

Service Will Not Start#

  • Confirm port 8010 is not already in use:

    ss -ltnp | grep 8010

  • Confirm the active config file is valid YAML. The service loads config.yaml, then applies AUDIO_ANALYZER__... environment overrides. The same config.yaml is used by both standalone and container runs (bind-mounted into the container).

First Startup Is Slow#

This is expected. On first run the service may download or export model assets to models/ and the Hugging Face cache. Subsequent starts reuse the cached artifacts.

health Endpoint Fails#

  • For Docker: check docker compose ps and docker compose logs -f audio-analyzer.

  • For standalone: confirm the process is running and bound to the expected host/port (defaults 127.0.0.1:8010).

  • If you are behind a corporate proxy, pass --noproxy '*' to curl when hitting 127.0.0.1.

GPU Path Is Not Used#

  • The OpenVINO GPU device requires the Intel/OpenVINO host GPU runtime installed on the host (separate from the Python dependencies).

  • For the container, /dev/dri must be exposed to the container (default in docker-compose.yml).

  • Docker vs host .venv: The Docker Compose environment is the verified configuration for GPU and NPU acceleration. Running directly with the host .venv may report only CPU in openvino.Core().available_devices if the host Intel GPU/NPU runtime stack is not fully installed. In that case, startup fails fast with a message such as:

    RuntimeError: Configured OpenVINO ASR device 'GPU' is not visible in this runtime.
OpenVINO available_devices=['CPU'].

    This is a host runtime environment limitation, not an application bug. Use the Docker Compose flow (docker compose up -d --build) for GPU and NPU acceleration; the container image includes the necessary OpenVINO GPU and NPU runtime libraries and exposes /dev/dri by default.

NPU Path Is Not Used#

  • Confirm the host exposes the NPU device node you intend to map. On Meteor Lake systems this is commonly /dev/accel/accel0.

  • Set ACCEL_MOUNT_PATH to that host device node for Compose runs.

  • ACCEL_MOUNT_PATH is the host-side path; Compose maps it to the fixed container path /dev/accel/accel0.

  • Keep ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.so in the container environment.

  • Make sure the container runs with the host render group via RENDER_GID so the app user can access the Intel NPU device node.

  • If core.available_devices still reports only CPU, re-check that you are using the NPU-capable image built from the updated Dockerfile and that the host Intel NPU driver stack is installed and loaded.

Recommended verification sequence:

  1. Verify host NPU node:

ls -l /dev/accel/

  1. Verify resolved Compose device mapping:

docker compose config

Under services.audio-analyzer.devices, confirm:

  • with ACCEL_MOUNT_PATH set:

    • source: <your host NPU path>

    • target: /dev/accel/accel0

  • without ACCEL_MOUNT_PATH set:

    • source: /dev/null

    • target: /dev/accel/accel0

  1. Verify container sees the mapped NPU node:

docker compose exec audio-analyzer ls -l /dev/accel/

  1. Verify OpenVINO runtime sees NPU inside the container:

docker compose exec audio-analyzer python3 -c "import openvino as ov; print([str(d).upper() for d in ov.Core().available_devices])"

  1. Verify startup validation passes and service is healthy:

docker compose logs -f audio-analyzer
curl --noproxy '*' http://127.0.0.1:8010/health

The service validates requested ASR provider/device at startup and fails fast when a configured device is unsupported or not visible in OpenVINO.

When device: NPU is configured but NPU is not available, startup fails with a runtime validation error similar to:

RuntimeError: Configured OpenVINO ASR device 'NPU' is not visible in this runtime.
OpenVINO available_devices=['CPU', 'GPU'].
For NPU, ensure ACCEL_MOUNT_PATH maps the host NPU node into /dev/accel/accel0
and ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.so is set.

whisper-large Rejected at Startup on NPU#

If startup fails with an error like:

RuntimeError: Model 'whisper-large' with device=NPU is not supported on this NPU hardware
(confirmed ZE_RESULT_ERROR_UNINITIALIZED at pfnAppendGraphExecute on Intel Core Ultra
NPU architecture 3720 with OpenVINO 2026.1). ...

this is a confirmed NPU driver/firmware limitation, not an Audio Analyzer bug.

Root cause: whisper-large (1.55 B parameters, 32 decoder layers, ~5.9 GB FP32 weights) fails at the Level Zero pfnAppendGraphExecute API during inference on Intel Core Ultra “AI Boost” NPU (architecture 3720). The NPU driver compiles the model successfully — startup takes ~200 s — but cannot execute the resulting graph at inference time. The Level Zero error code is ZE_RESULT_ERROR_UNINITIALIZED (0x78000001). OpenVINO reports “no fallback possible”.

This was verified with:

  • Hardware: Intel Core Ultra (Meteor Lake), NPU Intel(R) AI Boost, architecture 3720

  • OpenVINO: 2026.1.0-21367-63e31528c62

  • OpenVINO-GenAI: 2026.1.0.0-2957-1dabb8c2255

  • NPU compiler type: DRIVER (driver-integrated compiler, version 524289)

  • Standalone reproduction: ov_genai.WhisperPipeline loads successfully but pipe.generate() raises RuntimeError on the first inference call

Validated pass: whisper-tiny, whisper-base, whisper-small, and whisper-medium all complete NPU inference successfully on the same hardware with the same driver.

Workaround: Use device: CPU or device: GPU for whisper-large. Both pass full inference validation.

If a future NPU driver update resolves this: remove "whisper-large" from _OPENVINO_NPU_INFERENCE_UNSUPPORTED in utils/openvino_runtime_validation.py and rerun the full validation matrix:

# Minimal standalone repro to confirm whether a driver update fixes the issue
docker run --rm --user 1000:1000 --group-add <RENDER_GID> \
  --device /dev/dri:/dev/dri \
  --device <ACCEL_MOUNT_PATH>:/dev/accel/accel0 \
  -e ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.so \
  -v audio-analyzer_audio_analyzer_models:/app/audio_analyzer/models \
  intel/audio-analyzer:<VERSION> \
  python3 -c "
import numpy as np, openvino_genai as ov_genai
pipe = ov_genai.WhisperPipeline('/app/audio_analyzer/models/openvino/whisper-large', device='NPU')
r = pipe.generate(np.zeros(16000*3, dtype='float32'), return_timestamps=True)
print('PASS:', r.texts[0])
"

Invalid ASR Provider/Device Combination#

If startup fails with an error about models.asr.provider or models.asr.device, ensure your config matches the supported matrix:

  • openai: CPU only

  • whispercpp: CPU only

  • openvino: CPU | GPU | NPU

Example supported NPU configuration:

models:
  asr:
    provider: openvino
    device: NPU

When switching devices, restart the service/container and confirm logs.

Permission Errors on Mounted Folders#

The container runs as UID/GID 1000:1000 (baked into the image). Model, chunk, storage, and Hugging Face cache data are kept in named Docker volumes (audio_analyzer_{models,chunks,storage,cache}) initialized with that ownership, so this rarely fails on a fresh install. If you do see:

PermissionError: [Errno 13] Permission denied: '/app/audio_analyzer/storage/...'

you are most likely reusing volumes that were initialized by a previous run as a different UID (for example by an older root-only run). Reset them:

docker compose down
docker volume rm \
  audio-analyzer_audio_analyzer_models \
  audio-analyzer_audio_analyzer_chunks \
  audio-analyzer_audio_analyzer_storage \
  audio-analyzer_audio_analyzer_cache
docker compose up -d

Microphone / GET /devices Returns Empty#

  • Confirm ALSA capture devices exist on the host:

    arecord -l

  • For the container, uncomment the /dev/snd device mapping in docker-compose.yml.

FFmpeg or libsndfile Errors (Standalone)#

Install the required host packages:

sudo apt-get update
sudo apt-get install -y ffmpeg alsa-utils libsndfile1

Sessions / Transcripts Not Persisting#

Session files live under storage/<session_id>/. Confirm that directory is writable by the process and is on a persistent volume in container deployments.

Supporting Resources#