{"record":{"id":"cfe9305e952d16fe","repo":"langchain-ai/deepagents","slug":"media-path-must-be-a-local-filesystem-path-path","errorCode":null,"errorMessage":"media path must be a local filesystem path: {path}","messagePattern":"media path must be a local filesystem path: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/talon/deepagents_talon/media.py","lineNumber":214,"sourceCode":"\n    Args:\n        path: Candidate media path.\n        root: Directory that must contain the media after symlink resolution.\n        require_relative: Whether to reject absolute candidate paths up front.\n\n    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):","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/talon/deepagents_talon/media.py#L196-L232","documentation":"ValueError raised by resolve_bounded_media_path when the media path is not a plain local filesystem path — i.e. urlparse detects a URL scheme (http://, file://, s3://) that is not just a Windows drive letter. Remote or URI-style references are not allowed; only local paths.","triggerScenarios":"Passing 'https://cdn.example.com/img.png', 'file:///tmp/a.png', or 's3://bucket/x.png' as the media path.","commonSituations":"Reusing an attachment URL from an earlier API response instead of a local file; copying a URI from docs; confusing cloud storage paths with local paths.","solutions":["Download the remote file to a local path first and pass that path","Strip a 'file://' prefix and use the raw filesystem path","Pass a relative path under the outbound root"],"exampleFix":"// before\nresolve_bounded_media_path(Path(\"https://cdn.example.com/img.png\"), root)\n// after\nlocal = download(\"https://cdn.example.com/img.png\")  # returns Path under outbound root\nresolve_bounded_media_path(local, root)","handlingStrategy":"validation","validationCode":"from urllib.parse import urlparse\nraw = str(path)\nif urlparse(raw).scheme and not PureWindowsPath(raw).drive:\n    raise ValueError(f\"must be a local path, not a URI: {raw}\")","typeGuard":"def is_local_path(p: Path) -> bool:\n    raw = str(p)\n    return not urlparse(raw).scheme or bool(PureWindowsPath(raw).drive)","tryCatchPattern":"try:\n    resolved = resolve_bounded_media_path(path, root)\nexcept ValueError as exc:\n    logger.error(\"Bad media path: %s\", exc)\n    return None","preventionTips":["Treat attachment URLs as things to download first, never as media paths","Strip file:// prefixes at ingestion boundaries","Enforce local-path inputs in your own attachment-building layer"],"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"}