# Troubleshooting ## Service Will Not Start - Confirm port `8010` is not already in use: ```bash 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: ```text 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: ```bash ls -l /dev/accel/ ``` 2. Verify resolved Compose device mapping: ```bash docker compose config ``` Under `services.audio-analyzer.devices`, confirm: - with `ACCEL_MOUNT_PATH` set: - `source: ` - `target: /dev/accel/accel0` - without `ACCEL_MOUNT_PATH` set: - `source: /dev/null` - `target: /dev/accel/accel0` 3. Verify container sees the mapped NPU node: ```bash docker compose exec audio-analyzer ls -l /dev/accel/ ``` 4. Verify OpenVINO runtime sees NPU inside the container: ```bash docker compose exec audio-analyzer python3 -c "import openvino as ov; print([str(d).upper() for d in ov.Core().available_devices])" ``` 5. Verify startup validation passes and service is healthy: ```bash 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: ```text 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: ```text 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: ```bash # Minimal standalone repro to confirm whether a driver update fixes the issue docker run --rm --user 1000:1000 --group-add \ --device /dev/dri:/dev/dri \ --device :/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: \ 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`: `CPU` only - `whispercpp`: `CPU` only - `openvino`: `CPU` | `GPU` | `NPU` Example supported NPU configuration: ```yaml 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: ```text 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: ```bash 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: ```bash 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: ```bash sudo apt-get update sudo apt-get install -y ffmpeg alsa-utils libsndfile1 ``` ## Sessions / Transcripts Not Persisting Session files live under `storage//`. Confirm that directory is writable by the process and is on a persistent volume in container deployments. ## Supporting Resources - [Configuration Guide](./get-started/configuration.md) - [API Reference](./api-reference.md) - [System Requirements](./get-started/system-requirements.md)