{"record":{"id":"37214923af7440f0","repo":"Panniantong/Agent-Reach","slug":"binary-not-found-in-path","errorCode":null,"errorMessage":"{binary} not found in PATH","messagePattern":"(.+?) not found in PATH","errorType":"exception","errorClass":"MissingDependency","httpStatus":null,"severity":"error","filePath":"agent_reach/transcribe.py","lineNumber":80,"sourceCode":"\n\nclass MissingDependency(TranscribeError):\n    \"\"\"Raised when a required external binary is missing.\"\"\"\n\n\nclass NoProviderConfigured(TranscribeError):\n    \"\"\"Raised when no provider has an API key configured.\"\"\"\n\n\n_BLOCKED_HOSTS = {\n    \"localhost\",\n    \"metadata.google.internal\",\n}\n\n\ndef _require(binary: str) -> None:\n    if not shutil.which(binary):\n        raise MissingDependency(f\"{binary} not found in PATH\")\n\n\ndef _require_size_at_most(path: Path, limit: int, label: str) -> int:\n    \"\"\"Return file size or fail before expensive downstream processing.\"\"\"\n    size = path.stat().st_size\n    if size > limit:\n        limit_mib = limit / (1024 * 1024)\n        raise TranscribeError(f\"{label} exceeds safety limit of {limit_mib:g} MiB\")\n    return size\n\n\ndef _probe_audio_duration(path: Path) -> float:\n    \"\"\"Return duration in seconds or fail closed before media generation.\"\"\"\n    _require(\"ffprobe\")\n    cmd = [\n        \"ffprobe\",\n        \"-v\",\n        \"error\",","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/Panniantong/Agent-Reach/blob/93ae1d18c37b707dec053c7c4f9d91cd8ef8943d/agent_reach/transcribe.py#L62-L98","documentation":"Raised by _require() in agent_reach/transcribe.py (as MissingDependency, a TranscribeError subclass) when shutil.which() cannot find the named external binary — in practice 'ffmpeg' or 'ffprobe' — in PATH. The transcription pipeline shells out to ffmpeg/ffprobe, so they must be installed on the host, not pip-installed.","triggerScenarios":"Any transcribe call on a host without ffmpeg/ffprobe installed, or where they are installed but the directory is not on PATH (common in cron, systemd, or IDE-spawned shells).","commonSituations":"Fresh container/CI image without the ffmpeg package; macOS using a python.org interpreter that drops Homebrew /opt/homebrew/bin from PATH; Windows without ffmpeg on PATH.","solutions":["Install the binaries: apt-get install ffmpeg / brew install ffmpeg / winget install ffmpeg","Verify with `ffprobe -version` in the exact environment that runs the code","For service managers, set PATH explicitly (e.g. Environment= in systemd units) or pass an absolute path by symlinking into /usr/local/bin"],"exampleFix":"# before: MissingDependency: ffprobe not found in PATH\ntranscribe_audio(path)\n\n# after (debian/ubuntu)\nsudo apt-get install -y ffmpeg\ntranscribe_audio(path)","handlingStrategy":"validation","validationCode":"import shutil\nmissing = [b for b in ('ffmpeg', 'ffprobe') if not shutil.which(b)]\nif missing:\n    raise RuntimeError(f'install required binaries: {missing}')","typeGuard":"def transcribe_ready() -> bool:\n    import shutil\n    return all(shutil.which(b) for b in ('ffmpeg', 'ffprobe'))","tryCatchPattern":"from agent_reach.transcribe import MissingDependency\ntry:\n    transcribe_audio(path)\nexcept MissingDependency as e:\n    raise SystemExit(f'prerequisite missing: {e}; install ffmpeg') from e","preventionTips":["Add ffmpeg to container/CI images","Check shutil.which in a startup doctor rather than at transcription time","Beware PATH differences under cron/systemd/IDE launchers"],"tags":["dependency","ffmpeg","environment","path"],"backgroundTag":null,"analyzedSha":"93ae1d18c37b707dec053c7c4f9d91cd8ef8943d","analyzedAt":"2026-08-14T22:54:06.735Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}