langchain-ai/deepagents · error · RuntimeError

ffmpeg conversion failed with exit code

Error message

ffmpeg conversion failed with exit code {proc.returncode}: {stderr}

What it means

After ffmpeg runs, `_convert_to_wav` checks the exit code. A non-zero exit means conversion failed, and ffmpeg's decoded stderr is included in this RuntimeError to explain why (corrupt file, unsupported codec, unreadable path, etc.).

Solutions

Read the stderr embedded in the message to identify the codec/IO problem
Validate the input file is a complete, decodable media file (e.g. `ffprobe <file>` succeeds) before transcribing
Re-encode or re-export the source file to a common format (mp3/m4a/wav) and retry

Example fix

# before
transcribe(partial_download.webm)  # zero-byte / truncated file
# after
if not path.stat().st_size:
    raise ValueError("uploaded audio is empty")
transcribe(path)

Defensive patterns

Strategy: validation

Validate before calling

import subprocess
probe = subprocess.run(["ffprobe", "-v", "error", str(path)], capture_output=True)
if probe.returncode != 0:
    raise ValueError(f"unreadable audio {path}: {probe.stderr.decode(errors='replace')}")

Try / catch

try:
    text = transcribe_local(path)
except RuntimeError as exc:
    if str(exc).startswith("ffmpeg conversion failed"):
        logger.error("bad media file: %s", exc)
        text = ""
    else:
        raise

Prevention

Validate uploads (size, container, codec) before transcription
Re-encode user uploads to mp3/wav on ingest
Use an ffmpeg build with the codecs your users actually send (e.g. libfdk/aac)

When it happens

Trigger: Local transcription of an audio file that ffmpeg cannot decode: corrupted/truncated uploads, unsupported containers/codecs in the ffmpeg build, or an input path that exists but is unreadable.

Common situations: Users uploading voice notes with exotic codecs (e.g. AMR, WMA); zero-byte or partial downloads; ffmpeg builds compiled without proprietary decoders (e.g. no AAC on some minimal builds).

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/7e60f9d60c2d7c01. Report an issue: GitHub.

Appendix: source

Thrown at libs/talon/deepagents_talon/speech.py:308

                "-f",
                "wav",
                str(output),
            ],
            capture_output=True,
            timeout=120,
            check=False,
        )
    except FileNotFoundError as exc:
        msg = "ffmpeg not found on PATH; install ffmpeg to enable voice transcription."
        raise RuntimeError(msg) from exc
    except subprocess.TimeoutExpired as exc:
        msg = f"ffmpeg timed out while converting {path}"
        raise RuntimeError(msg) from exc

    if proc.returncode != 0:
        stderr = proc.stderr.decode("utf-8", errors="replace")
        msg = f"ffmpeg conversion failed with exit code {proc.returncode}: {stderr}"
        raise RuntimeError(msg)
    return output

View on GitHub (pinned to a1af029e6e)