{"record":{"id":"9342b7ee036ffb9e","repo":"jamiepine/voicebox","slug":"file-not-found-audio-path","errorCode":null,"errorMessage":"File not found: {audio_path}","messagePattern":"File not found: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/mcp_server/tools.py","lineNumber":147,"sourceCode":"        if bool(audio_base64) == bool(audio_path):\n            raise ValueError(\n                \"Pass exactly one of `audio_base64` or `audio_path`.\"\n            )\n\n        # Absolute-path mode: validate and transcribe in place. Restricted\n        # to loopback callers so a Voicebox bound on 0.0.0.0 doesn't double\n        # as an unauthenticated arbitrary-local-file read primitive.\n        if audio_path is not None:\n            if not request_is_loopback():\n                raise ValueError(\n                    \"`audio_path` is only available to loopback callers — \"\n                    \"remote callers must use `audio_base64`.\"\n                )\n            path = Path(audio_path)\n            if not path.is_absolute():\n                raise ValueError(\"`audio_path` must be absolute.\")\n            if not path.is_file():\n                raise ValueError(f\"File not found: {audio_path}\")\n            if path.stat().st_size > MAX_TRANSCRIBE_BYTES:\n                raise ValueError(\n                    f\"File exceeds {MAX_TRANSCRIBE_BYTES // (1024 * 1024)} MB limit.\"\n                )\n            return await _transcribe_file(path, language, model)\n\n        # Base64 mode: decode into a temp file, transcribe, clean up.\n        try:\n            raw = b64.b64decode(audio_base64, validate=True)\n        except Exception as exc:\n            raise ValueError(f\"Invalid audio_base64: {exc}\") from exc\n        if len(raw) > MAX_TRANSCRIBE_BYTES:\n            raise ValueError(\n                f\"Audio exceeds {MAX_TRANSCRIBE_BYTES // (1024 * 1024)} MB limit.\"\n            )\n        with tempfile.NamedTemporaryFile(\n            suffix=\".wav\", delete=False\n        ) as tmp:","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/jamiepine/voicebox/blob/51f49dea198384b4eb6087b72c17057c6eb1c1cd/backend/mcp_server/tools.py#L129-L165","documentation":"Raised by voicebox_transcribe when audio_path passes the loopback and absolute checks but Path(audio_path).is_file() is False — i.e. nothing readable exists at that path when the server checks.","triggerScenarios":"Pointing audio_path at a path that does not exist, is a directory, lives outside an unmounted volume, or is unreadable due to permissions (the is_file check can fail on broken symlinks).","commonSituations":"Client and server disagree on the filesystem (container vs host paths); file was deleted between submission and check; wrong working directory used to build an 'absolute' path; permission mode hides the file from the Voicebox process.","solutions":["Confirm the file exists from the Voicebox server's perspective (not the client's): ls -l on the host/container.","Mount/share the directory into the Voicebox process if it runs in a container.","Check the Voicebox process has read permission on the file.","Re-verify the path is absolute and points to a regular file, not a directory or symlink."],"exampleFix":"// before\nvoicebox_transcribe(audio_path=\"/data/clip.wav\")  # missing on server\n// after\n# ensure /data is mounted into the Voicebox container, then\nvoicebox_transcribe(audio_path=\"/data/clip.wav\")","handlingStrategy":"validation","validationCode":"from pathlib import Path\np = Path(audio_path)\nif not p.is_absolute() or not p.is_file():\n    raise FileNotFoundError(f\"audio not found or not absolute: {audio_path}\")\nawait voicebox_transcribe(audio_path=str(p))","typeGuard":"def audio_path_is_readable(value: str) -> bool:\n    from pathlib import Path\n    p = Path(value)\n    return p.is_absolute() and p.is_file() and p.stat().st_size > 0","tryCatchPattern":"try:\n    await voicebox_transcribe(audio_path=audio_path)\nexcept ValueError as exc:\n    if \"File not found\" in str(exc):\n        # verify on the server host, remount storage if needed, then retry\n        raise FileNotFoundError(f\"server cannot read {audio_path}; check mounts/permissions\")\n    raise","preventionTips":["If Voicebox runs in a container, mount the audio directory into it.","Confirm the file is readable by the Voicebox process uid.","Validate existence+readability on the server host before each call."],"tags":["mcp","filesystem","transcription","containerization"],"backgroundTag":null,"analyzedSha":"51f49dea198384b4eb6087b72c17057c6eb1c1cd","analyzedAt":"2026-08-12T16:51:42.824Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}