sgl-project/sglang · error · ValueError

Invalid audio format: {audio_file}

Error message

Invalid audio format: {audio_file}

What it means

load_audio accepts bytes, http(s) URLs, file:// URI paths, or plain local path strings; any other type (None, int, list) hits the final else branch and raises. The message echoes the offending value to make the bad input identifiable in multimodal request logs.

Source

Thrown at python/sglang/srt/utils/common.py:1709

    if sr is None:
        sr = 16000

    # Normalize input: resolve URL / base64 / file:// to bytes or path
    if isinstance(audio_file, bytes):
        source = audio_file
    elif isinstance(audio_file, str) and audio_file.startswith("data:"):
        source = pybase64.b64decode(audio_file.split(",")[1], validate=True)
    elif isinstance(audio_file, str) and (
        audio_file.startswith("http://") or audio_file.startswith("https://")
    ):
        timeout = int(os.getenv("REQUEST_TIMEOUT", "5"))
        source = download_remote_media(audio_file, timeout=timeout)
    elif isinstance(audio_file, str) and audio_file.startswith("file://"):
        source = unquote(urlparse(audio_file).path)
    elif isinstance(audio_file, str):
        source = audio_file
    else:
        raise ValueError(f"Invalid audio format: {audio_file}")

    from sglang.srt.multimodal.audio_from_video import (
        decode_audio_container,
        is_audio_container,
    )

    if isinstance(source, bytes):
        header = source[:16]
    else:
        with open(source, "rb") as audio_stream:
            header = audio_stream.read(16)

    if is_audio_container(header):
        return decode_audio_container(
            source,
            target_sr=sr,
            mono=mono,
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Validate/require the audio field in request parsing before calling load_audio
2. Normalize input to str/bytes: coerce or reject with a 400 at the API layer
3. Check for None explicitly and return a proper client error

Example fix

# before
wav, sr = load_audio(req.get('audio'))  # None when key missing -> ValueError
# after
if not req.get('audio'): raise HTTPException(400, 'audio field required')
wav, sr = load_audio(req['audio'])

if not isinstance(audio_file, (str, bytes)) or not audio_file:
    return HTTPException(400, 'audio must be a non-empty string (url/path/base64) or bytes')
wav, sr = load_audio(audio_file, sr=sr)

def is_audio_input(v) -> bool:
    return isinstance(v, (str, bytes)) and len(v) > 0

try:
    wav, sr = load_audio(audio_file)
except ValueError as e:
    if 'Invalid audio format' in str(e):
        return HTTPException(400, str(e))
    raise

When it happens

Trigger: Calling load_audio(None), load_audio(123), or passing a non-str/bytes object from a chat template / request parser that failed to extract the audio field; e.g. an 'audio' key present but null in the request JSON.

Common situations: Clients sending {"audio": null} or numbers; frontend bugs forwarding the wrong JSON field; protobuf deserialization producing unexpected types.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• unsupported audio item: loaded={loaded_type}, raw={raw_type}
• Invalid image: {image_file}
• Unsupported image type: {type(image)}
• Z-Image text embeddings must have shape [seq, dim] or [batch
• When using multiple prompts with multiple input images, prov

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/8092f3e25f63fd56. Report an issue: GitHub.