{"record":{"id":"80c098a86b75c4b9","repo":"langchain-ai/deepagents","slug":"media-path-must-be-a-local-relative-path-under-the","errorCode":null,"errorMessage":"media path must be a local relative path under the outbound root: {path}","messagePattern":"media path must be a local relative path under the outbound root: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/talon/deepagents_talon/media.py","lineNumber":220,"sourceCode":"    Returns:\n        Canonical media path under `root`.\n\n    Raises:\n        ValueError: If the path is unsafe, unavailable, or escapes `root`.\n    \"\"\"\n    raw = str(path)\n    parsed = urlparse(raw)\n    windows_path = PureWindowsPath(raw)\n    is_windows_drive_path = bool(windows_path.drive)\n    if parsed.scheme and not is_windows_drive_path:\n        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","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/talon/deepagents_talon/media.py#L202-L238","documentation":"ValueError raised by resolve_bounded_media_path when the path is absolute, a Windows absolute/drive path, or starts with '~' while require_relative is set. Media must resolve within the outbound root, so home-expanding or absolute paths are rejected.","triggerScenarios":"Passing '/home/user/pic.jpg', 'C:\\\\pics\\\\a.png', or '~/pic.jpg' when require_relative=True (the default for outbound media).","commonSituations":"Using an absolute path copied from a file manager; scripts built on the developer machine using absolute paths; tilde shorthand assumed to expand.","solutions":["Copy the file into the outbound root directory and pass a path relative to it","Pass require_relative=False only if your use case genuinely allows absolute paths (validate_media paths)","Expand '~' yourself into the outbound root and re-express the path relatively"],"exampleFix":"// before\nresolve_bounded_media_path(Path(\"~/Pictures/pic.jpg\"), root)\n// after\nshutil.copy(Path(\"~/Pictures/pic.jpg\").expanduser(), root / \"pic.jpg\")\nresolve_bounded_media_path(Path(\"pic.jpg\"), root)","handlingStrategy":"validation","validationCode":"raw = str(path)\nif raw.startswith(\"~\") or Path(raw).is_absolute() or PureWindowsPath(raw).drive:\n    raise ValueError(f\"must be relative under outbound root: {raw}\")","typeGuard":"def is_relative_media_path(p: Path) -> bool:\n    raw = str(p)\n    return not raw.startswith(\"~\") and not p.is_absolute() and not PureWindowsPath(raw).is_absolute()","tryCatchPattern":"try:\n    resolved = resolve_bounded_media_path(path, root)\nexcept ValueError as exc:\n    logger.error(\"Media path not relative to outbound root: %s\", exc)\n    return None","preventionTips":["Copy external/absolute files into the outbound root and reference them relatively","Expand '~' at the boundary and re-express paths relative to root","Standardize on root-relative paths throughout your pipeline"],"tags":["media","path","validation","security"],"backgroundTag":"invalid-media-path","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}