langchain-ai/deepagents · error · RuntimeError

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

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.).

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)

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.