microsoft/VibeVoice · critical · RuntimeError

MODEL_PATH not set in environment

Error message

MODEL_PATH not set in environment

What it means

Raised by the FastAPI startup hook in demo/web/app.py: the app requires the MODEL_PATH environment variable to point at the VibeVoice streaming model checkpoint, and refuses to start without it. It is a hard configuration gate before any model loading begins.

Source

Thrown at demo/web/app.py:345

            thread.join()
            if errors:
                emit("generation_error", message=str(errors[0]))
                raise errors[0]

    def chunk_to_pcm16(self, chunk: np.ndarray) -> bytes:
        chunk = np.clip(chunk, -1.0, 1.0)
        pcm = (chunk * 32767.0).astype(np.int16)
        return pcm.tobytes()


app = FastAPI()


@app.on_event("startup")
async def _startup() -> None:
    model_path = os.environ.get("MODEL_PATH")
    if not model_path:
        raise RuntimeError("MODEL_PATH not set in environment")

    device = os.environ.get("MODEL_DEVICE", "cuda")
    
    service = StreamingTTSService(
        model_path=model_path,
        device=device
    )
    service.load()

    app.state.tts_service = service
    app.state.model_path = model_path
    app.state.device = device
    app.state.websocket_lock = asyncio.Lock()
    print("[startup] Model ready.")


def streaming_tts(text: str, **kwargs) -> Iterator[np.ndarray]:
    service: StreamingTTSService = app.state.tts_service

View on GitHub (pinned to 94da20d98b)

Solutions

1. Export MODEL_PATH to the streaming model directory before starting: export MODEL_PATH=/path/to/VibeVoiceStreaming then uvicorn ...
2. Verify with echo "$MODEL_PATH" in the same shell/session that launches the server.
3. For Docker/systemd, pass the variable explicitly (-e MODEL_PATH=... / Environment=MODEL_PATH=...).
4. Optionally wrap startup in a check that prints a clear message listing required env vars (MODEL_PATH, optional MODEL_DEVICE, VOICE_PRESET).

Example fix

# before
uvicorn web.app:app  # RuntimeError: MODEL_PATH not set

# after
export MODEL_PATH=/models/VibeVoiceStreaming
export MODEL_DEVICE=cuda
uvicorn web.app:app

import os
model_path = os.environ.get("MODEL_PATH")
if not model_path or not os.path.isdir(model_path):
    raise SystemExit("Set MODEL_PATH to the streaming model directory, e.g. export MODEL_PATH=/models/VibeVoiceStreaming")

When it happens

Trigger: Running uvicorn demo.web.app:app (or the container) without exporting MODEL_PATH; MODEL_PATH set to an empty string (falsy); env var set in a different shell/session than the one launching the server.

Common situations: Following the web demo README but skipping the export step; deploying to Docker/systemd where the env var was not passed through; typo'd variable name (e.g. MODEL_DIR).

Related errors

• Voices directory not found: {voices_dir}
• No voice preset (.pt) files found in {voices_dir}
• Voice preset {key!r} not found
• StreamingTTSService not initialized
• Unsupported decoder model type: {decoder_config.get('model_t

AI-assisted analysis of microsoft/VibeVoice@94da20d98b (2026-08-15). Data as JSON: /api/errors/ce7588eced529c13. Report an issue: GitHub.