BerriAI/litellm · error · NvidiaRivaException

numpy is required for Riva audio resampling. Install Riva ST

Error message

numpy is required for Riva audio resampling. Install Riva STT extras to enable automatic audio resampling: `pip install 'litellm[stt-nvidia-riva]'`

What it means

Raised by litellm's Riva audio utilities when numpy is not installed but automatic audio resampling to Riva's required 16 kHz mono PCM is needed. litellm keeps numpy out of core dependencies, so the Riva STT path raises this actionable ImportError wrapper pointing at the stt-nvidia-riva extra.

Source

Thrown at litellm/llms/nvidia_riva/audio_transcription/audio_utils.py:53

@dataclass
class ResampledAudio:
    pcm_bytes: bytes
    duration_seconds: float
    sample_rate_hz: int
    num_channels: int


def resample_to_riva_pcm(file_bytes: bytes) -> ResampledAudio:
    """
    Decode ``file_bytes`` and produce 16 kHz mono LINEAR_PCM (int16 little
    endian) suitable for streaming to Riva, plus the audio duration in
    seconds (used for cost calculation when Riva does not return usage).
    """
    try:
        import numpy as np
    except ImportError as e:
        raise NvidiaRivaException(
            status_code=500,
            message=f"numpy is required for Riva audio resampling. {_INSTALL_HINT}",
        ) from e

    samples_float, source_rate = _decode_to_float32(file_bytes)

    # Downmix to mono by averaging channels.
    if samples_float.ndim == 2 and samples_float.shape[1] > 1:
        samples_float = samples_float.mean(axis=1)
    elif samples_float.ndim == 2:
        samples_float = samples_float[:, 0]

    samples_float = np.asarray(samples_float, dtype=np.float32).ravel()

    if source_rate != RIVA_TARGET_SAMPLE_RATE_HZ:
        samples_float = _resample(samples_float, source_rate, RIVA_TARGET_SAMPLE_RATE_HZ)

    # Clip + convert float [-1, 1] to int16 little-endian PCM.

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. pip install 'litellm[stt-nvidia-riva]' which brings numpy plus audio decode deps.
2. Or pip install numpy directly if you only need resampling.
3. Alternatively pre-convert audio to 16 kHz mono wav so the resample path is skipped.
4. Rebuild your deployment image with the extra included.

Example fix

# before: Dockerfile
RUN pip install litellm

# after
RUN pip install 'litellm[stt-nvidia-riva]'

try:
    import numpy  # noqa: F401
except ImportError:
    raise RuntimeError("Install 'litellm[stt-nvidia-riva]' before using Riva STT resampling")

from litellm.exceptions import APIError
try:
    litellm.transcription(model="nvidia_riva/riva_asr", file=f)
except APIError as e:
    if "numpy is required" in str(e):
        raise RuntimeError("Environment missing dependency: pip install 'litellm[stt-nvidia-riva]'" ) from e
    raise

When it happens

Trigger: Calling litellm.transcription() with an nvidia_riva/* model on an environment without numpy, with audio that is not already 16 kHz mono wav (forcing the resample path resample_to_riva_pcm).

Common situations: Slim docker images / serverless runtimes that omit numpy, fresh venvs installing litellm without extras, or upgrading litellm in a project that never needed numpy before.

Related errors

• Could not decode audio for Riva STT. Install audio extras (`
• Audio decode produced no samples.
• Could not decode audio for Riva STT. Convert your audio to w
• Missing google.cloud package. Run `pip install --upgrade goo
• Redis client does not support Lua script registration

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/1241f3a7c03b3fb2. Report an issue: GitHub.