Troubleshooting#
Service Will Not Start#
Confirm port
8010is not already in use:ss -ltnp | grep 8010
Confirm the active config file is valid YAML. The service loads
config.yaml, then appliesAUDIO_ANALYZER__...environment overrides. The sameconfig.yamlis 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 psanddocker 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 '*'tocurlwhen hitting127.0.0.1.
GPU Path Is Not Used#
The OpenVINO
GPUdevice requires the Intel/OpenVINO host GPU runtime installed on the host (separate from the Python dependencies).For the container,
/dev/drimust be exposed to the container (default indocker-compose.yml).Docker vs host
.venv: The Docker Compose environment is the verified configuration for GPU and NPU acceleration. Running directly with the host.venvmay report onlyCPUinopenvino.Core().available_devicesif 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/driby 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_PATHto that host device node for Compose runs.ACCEL_MOUNT_PATHis the host-side path; Compose maps it to the fixed container path/dev/accel/accel0.Keep
ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.soin the container environment.Make sure the container runs with the host render group via
RENDER_GIDso the app user can access the Intel NPU device node.If
core.available_devicesstill reports onlyCPU, 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:
Verify host NPU node:
ls -l /dev/accel/
Verify resolved Compose device mapping:
docker compose config
Under services.audio-analyzer.devices, confirm:
with
ACCEL_MOUNT_PATHset:source: <your host NPU path>target: /dev/accel/accel0
without
ACCEL_MOUNT_PATHset:source: /dev/nulltarget: /dev/accel/accel0
Verify container sees the mapped NPU node:
docker compose exec audio-analyzer ls -l /dev/accel/
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])"
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.WhisperPipelineloads successfully butpipe.generate()raisesRuntimeErroron 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])
"
Coarse Segment Timestamps on NPU#
With provider: openvino and device: NPU, the OpenVINO GenAI backend runs
Whisper with return_timestamps off. Each decoded audio chunk comes back as
one segment that spans the whole chunk.
This is intended. With timestamps on, the NPU Whisper pipeline returned
corrupted text (repeated short fragments) or failed with
KV-Cache is full. This was seen with OpenVINO GenAI 2026.1 and 2026.3.
With diarization on, speaker labels follow the same chunks: two voices inside one chunk get one label.
If you need per-phrase timestamps or speaker labels, use device: CPU or
device: GPU.
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:CPUonlywhispercpp:CPUonlyopenvino: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 -lFor the container, uncomment the
/dev/snddevice mapping indocker-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.