{"record":{"id":"b72888f257fece01","repo":"sgl-project/sglang","slug":"could-not-decode-audio-e","errorCode":null,"errorMessage":"Could not decode audio: {e}","messagePattern":"Could not decode audio: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/common.py","lineNumber":1760,"sourceCode":"        except Exception as e:\n            # torchcodec's bytes-buffer IO can fail on WAV files that carry\n            # large trailing metadata chunks. Fall back to soundfile, which reads the PCM payload directly.\n            logger.warning(\n                f\"torchcodec AudioDecoder failed ({e}); falling back to soundfile + torchaudio.\"\n            )\n\n    # Fallback: soundfile + torchaudio (ARM / no FFmpeg / torchcodec failure)\n    import soundfile as sf\n    import torch\n    import torchaudio\n\n    try:\n        if isinstance(source, bytes):\n            audio, original_sr = sf.read(BytesIO(source))\n        else:\n            audio, original_sr = sf.read(source)\n    except sf.LibsndfileError as e:\n        raise ValueError(f\"Could not decode audio: {e}\") from e\n\n    if mono and len(audio.shape) > 1:\n        audio = np.mean(audio, axis=1)\n\n    if original_sr != sr:\n        audio_tensor = torch.from_numpy(audio).float()\n        if audio_tensor.dim() == 1:\n            audio_tensor = audio_tensor.unsqueeze(0)\n        else:\n            audio_tensor = audio_tensor.T\n        audio_tensor = torchaudio.functional.resample(\n            audio_tensor, orig_freq=original_sr, new_freq=sr\n        )\n        if audio_tensor.shape[0] == 1:\n            audio = audio_tensor.squeeze(0).numpy()\n        else:\n            audio = audio_tensor.T.numpy()\n","sourceCodeStart":1742,"sourceCodeEnd":1778,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/common.py#L1742-L1778","documentation":"libsndfile (via soundfile sf.read) failed to decode the audio source — the bytes/path were passed to the decoder but it could not parse the container or codec. The ValueError wraps LibsndfileError so callers get a uniform failure regardless of file vs bytes input.","triggerScenarios":"Passing an audio file in a format libsndfile does not support (e.g. raw AAC/ADTS, some MP4/M4A streams, or corrupt/truncated files) to load_audio; download truncated by timeout so bytes are incomplete; note some formats are routed to decode_audio_container earlier, so this path means that routing did not apply.","commonSituations":"User uploads voice-note .m4a/.aac that libsndfile can't handle; truncated downloads; 0-byte files; mislabeled extensions (mp3 content in .wav path usually works, but exotic codecs don't).","solutions":["Re-encode to WAV or FLAC (ffmpeg -i in.mp3 out.wav) before sending","Ensure downloads complete (raise media timeout / size limits) and the source file is not corrupt","Route MP4/M4A through the torchcodec/container decode path instead of sf.read (see is_audio_container/decode_audio_container)"],"exampleFix":"# before\nwav, sr = load_audio('note.aac')  # libsndfile can't decode -> ValueError\n# after (pre-convert)\n# ffmpeg -i note.aac note.wav\nwav, sr = load_audio('note.wav')","handlingStrategy":"try-catch","validationCode":"# pre-verify container is libsndfile-readable when format is uncertain\nimport soundfile as sf\nif isinstance(source, bytes):\n    sf.info(io.BytesIO(source))  # raises early with a clearer error","typeGuard":null,"tryCatchPattern":"try:\n    wav, sr = load_audio(path, sr=16000)\nexcept ValueError as e:\n    if 'Could not decode audio' in str(e):\n        return HTTPException(400, f'unsupported/corrupt audio: {e}')\n    raise","preventionTips":["Convert uploads to WAV/FLAC (ffmpeg) server-side before decode","Verify downloads completed (timeout/size guards) before decoding","Use the container-aware decode path for mp4/m4a"],"tags":["audio","multimodal","decode","libsndfile"],"backgroundTag":"audio-decode-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}