sgl-project/sglang · error · ValueError

Invalid audio format

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.

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: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid image
• unsupported audio item: loaded=
• An exception occurred while loading
• audio_cap must be non-negative, got
• audio must be a 2D tensor, but got

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

Appendix: 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)