{"record":{"id":"02a4ee8329a2b5fb","repo":"langchain-ai/deepagents","slug":"media-file-is-unavailable-path","errorCode":null,"errorMessage":"media file is unavailable: {path}","messagePattern":"media file is unavailable: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/talon/deepagents_talon/media.py","lineNumber":231,"sourceCode":"        msg = f\"media path must be a local filesystem path: {path}\"\n        raise ValueError(msg)\n    if raw.startswith(\"~\") or (\n        require_relative\n        and (path.is_absolute() or windows_path.is_absolute() or is_windows_drive_path)\n    ):\n        msg = f\"media path must be a local relative path under the outbound root: {path}\"\n        raise ValueError(msg)\n    if \"..\" in path.parts or \"..\" in windows_path.parts:\n        msg = f\"media path must not contain parent-directory traversal: {path}\"\n        raise ValueError(msg)\n\n    root_resolved = root.expanduser().resolve()\n    candidate_input = root_resolved / path if not path.is_absolute() else path\n    try:\n        candidate = candidate_input.resolve(strict=True)\n    except OSError as exc:\n        msg = f\"media file is unavailable: {path}\"\n        raise ValueError(msg) from exc\n    if not candidate.is_relative_to(root_resolved):\n        msg = f\"media path escapes outbound root: {path}\"\n        raise ValueError(msg)\n    if not candidate.is_file():\n        msg = f\"media path is not a regular file: {path}\"\n        raise ValueError(msg)\n    return candidate\n\n\ndef _document_parts(paths: list[Path]) -> list[str]:\n    parts: list[str] = []\n    for path in paths:\n        if path.suffix.lower() not in READABLE_DOCUMENT_EXTENSIONS:\n            parts.append(f\"_(Received unsupported document attachment: {path.name}.)_\")\n            continue\n        try:\n            if path.stat().st_size > MAX_TEXT_DOCUMENT_BYTES:\n                parts.append(f\"_(Document attachment is too large to read inline: {path.name}.)_\")","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/talon/deepagents_talon/media.py#L213-L249","documentation":"ValueError raised by resolve_bounded_media_path when resolve(strict=True) raises OSError — the file (or an intermediate symlink target) does not exist or is unreachable. The original OSError is chained as __cause__.","triggerScenarios":"Passing a path to a file that was deleted/moved, a dangling symlink, or a path with an unreadable intermediate directory.","commonSituations":"Media written asynchronously and read before the write completes; typo'd filename; files cleaned up by a temp-file sweeper before send; wrong working directory assumption.","solutions":["Verify the file exists at root / relative-path before calling (Path.exists() and is_file())","Fix the filename/relative path typo","Ensure the producer finished writing (and closed) the file before sending; check symlink targets exist"],"exampleFix":"// before\nmedia = outbound_channel_media(ref)  # ref.path=\"outbox/a.png\" but file not written yet\n// after\npath = root / ref.path\nif not path.is_file():\n    raise FileNotFoundError(path)\nmedia = outbound_channel_media(ref)","handlingStrategy":"validation","validationCode":"target = root / relative\nif not target.exists():\n    raise FileNotFoundError(target)\nif target.is_symlink() and not target.resolve(strict=False).exists():\n    raise FileNotFoundError(f\"dangling symlink: {target}\")","typeGuard":null,"tryCatchPattern":"try:\n    resolved = resolve_bounded_media_path(path, root)\nexcept ValueError as exc:\n    logger.error(\"Media file unavailable: %s (cause: %r)\", exc, exc.__cause__)\n    return None","preventionTips":["Check Path.is_file() before sending media","Synchronize producers/consumers so files are fully written before send","Watch for cleanup jobs removing files between creation and send"],"tags":["media","filesystem","path"],"backgroundTag":"file-not-found","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}