{"record":{"id":"cb3f0fbc3a8f7e24","repo":"jamiepine/voicebox","slug":"could-not-decode-audio-decode-err","errorCode":null,"errorMessage":"Could not decode audio: {decode_err}","messagePattern":"Could not decode audio: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"backend/routes/generations.py","lineNumber":463,"sourceCode":"            )\n        chunks.append(chunk)\n    audio_bytes = b\"\".join(chunks)\n    if not audio_bytes:\n        raise HTTPException(status_code=400, detail=\"Empty audio file.\")\n\n    generation_id = str(uuid.uuid4())\n    target = config.get_generations_dir() / f\"{generation_id}{suffix}\"\n    target.write_bytes(audio_bytes)\n\n    try:\n        audio, sr = load_audio(str(target))\n        duration = float(len(audio) / sr) if sr else 0.0\n    except Exception as decode_err:\n        try:\n            target.unlink()\n        except OSError:\n            pass\n        raise HTTPException(\n            status_code=400,\n            detail=f\"Could not decode audio: {decode_err}\",\n        ) from decode_err\n\n    profile = _get_or_create_import_profile(db)\n    display_name = Path(file.filename or \"Imported audio\").stem or \"Imported audio\"\n\n    return await history.create_generation(\n        profile_id=profile.id,\n        text=display_name,\n        language=\"en\",\n        audio_path=config.to_storage_path(target),\n        duration=duration,\n        seed=None,\n        db=db,\n        generation_id=generation_id,\n        status=\"completed\",\n        engine=\"import\",","sourceCodeStart":445,"sourceCodeEnd":481,"githubUrl":"https://github.com/jamiepine/voicebox/blob/51f49dea198384b4eb6087b72c17057c6eb1c1cd/backend/routes/generations.py#L445-L481","documentation":"Returned by POST /generate/import when `load_audio(str(target))` raises any Exception after the bytes were written to disk. The handler deletes the orphaned target file (best-effort, OSError ignored) and re-raises as HTTP 400 with the original exception text. This means the container/format was accepted by extension but the actual audio decoder (torchaudio/soundfile/etc.) could not parse the contents.","triggerScenarios":"A file with a whitelisted extension (e.g. .wav) whose contents are corrupt, truncated, or not actually that format; an encoding variant the backend decoder doesn't support (e.g. 32-bit float WAV when only 16-bit PCM is supported); a password-protected or DRM blob renamed to .mp3.","commonSituations":"Renamed a non-audio file to .wav; partial download of an audio file; exotic codec profile (e.g. very high sample rate, unusual channel layout) unsupported by the bundled decoder library; FFmpeg/torchaudio backend missing on the server.","solutions":["Read the decode_err message — it usually names the missing codec or parse failure.","Re-encode the source to standard PCM WAV (16-bit, 44.1kHz, mono/stereo) using ffmpeg before importing.","Ensure the server has the required audio decoder backend installed (torchaudio + soundfile/ffmpeg).","If a specific format is unsupported by the decoder, remove it from IMPORT_AUDIO_EXTENSIONS so it fails at the extension check with a clearer message."],"exampleFix":"# before: rename and hope\nmv data.bin audio.wav\n\n# after: re-encode to a known-good container\nffmpeg -i data.bin -ar 44100 -ac 1 -sample_fmt s16 audio.wav","handlingStrategy":"try-catch","validationCode":"// Best-effort: validate extension + non-empty before the decode attempt\nif (!hasImportableAudioExt(file.name) || file.size === 0) return;\n// Full decode validation only happens server-side; cannot pre-verify codec here.\nawait upload(file);","typeGuard":"// Cannot type-guard codec validity client-side; guard extension + size only\nfunction plausiblyDecodable(file) {\n  return isNonEmptyFile(file) && hasImportableAudioExt(file.name);\n}","tryCatchPattern":"try {\n  const res = await fetch('/generate/import', { method:'POST', body: form });\n  if (res.status === 400 && /decode/i.test((await res.json()).detail)) {\n    alert('Could not decode — re-encode to standard WAV/MP3');\n    return;\n  }\n} catch (e) { console.error(e); }","preventionTips":["Re-encode sources to standard PCM WAV before importing.","Ensure the server has torchaudio/soundfile/ffmpeg installed.","Remove unsupported-but-whitelisted extensions from IMPORT_AUDIO_EXTENSIONS."],"tags":["fastapi","file-upload","audio","decode","import","torchaudio","soundfile"],"backgroundTag":null,"analyzedSha":"51f49dea198384b4eb6087b72c17057c6eb1c1cd","analyzedAt":"2026-08-12T16:51:42.824Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}