{"record":{"id":"1a01e6e3349eaf7c","repo":"langchain-ai/deepagents","slug":"windows-absolute-paths-are-not-supported-path","errorCode":null,"errorMessage":"Windows absolute paths are not supported: {path}. Please use virtual paths starting with / (e.g., /workspace/file.txt)","messagePattern":"Windows absolute paths are not supported: (.+?)\\. Please use virtual paths starting with / \\(e\\.g\\., /workspace/file\\.txt\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/backends/utils.py","lineNumber":707,"sourceCode":"        validate_path(\"foo/bar\")  # Returns: \"/foo/bar\"\n        validate_path(\"/./foo//bar\")  # Returns: \"/foo/bar\"\n        validate_path(\"../etc/passwd\")  # Raises ValueError\n        validate_path(r\"C:\\\\Users\\\\file.txt\")  # Raises ValueError\n        validate_path(\"/data/file.txt\", allowed_prefixes=[\"/data/\"])  # OK\n        validate_path(\"/etc/file.txt\", allowed_prefixes=[\"/data/\"])  # Raises ValueError\n        ```\n    \"\"\"\n    # Check for traversal as a path component (not substring) to avoid\n    # false-positive rejection of legitimate filenames like \"foo..bar.txt\"\n    parts = PurePosixPath(to_posix_path(path)).parts\n    if \"..\" in parts or path.startswith(\"~\"):\n        msg = f\"Path traversal not allowed: {path}\"\n        raise ValueError(msg)\n\n    # Reject Windows absolute paths (e.g., C:\\..., D:/...)\n    if re.match(r\"^[a-zA-Z]:\", path):\n        msg = f\"Windows absolute paths are not supported: {path}. Please use virtual paths starting with / (e.g., /workspace/file.txt)\"\n        raise ValueError(msg)\n\n    normalized = os.path.normpath(path)\n    normalized = normalized.replace(\"\\\\\", \"/\")\n\n    if not normalized.startswith(\"/\"):\n        normalized = f\"/{normalized}\"\n\n    # Defense-in-depth: verify normpath didn't produce traversal\n    if \"..\" in normalized.split(\"/\"):\n        msg = f\"Path traversal detected after normalization: {path} -> {normalized}\"\n        raise ValueError(msg)\n\n    if allowed_prefixes is not None and not any(normalized.startswith(prefix) for prefix in allowed_prefixes):\n        msg = f\"Path must start with one of {allowed_prefixes}: {path}\"\n        raise ValueError(msg)\n\n    return normalized\n","sourceCodeStart":689,"sourceCodeEnd":725,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/backends/utils.py#L689-L725","documentation":"The virtual filesystem is POSIX-rooted, so Windows absolute paths (drive letters like `C:\\...` or `D:/...`) are not valid and are rejected by `validate_path` with guidance to use `/`-rooted virtual paths. This keeps path semantics consistent across hosts.","triggerScenarios":"Calling backend operations with `C:\\Users\\me\\file.txt` or `D:/data/x.csv`; passing Windows paths from environment variables, configs, or user input on Windows hosts; LLM emitting OS-native paths in tool calls.","commonSituations":"Running the agent on Windows and reusing local file paths directly; hard-coded Windows paths in prompts or examples; mixing local filesystem code with the virtual path layer.","solutions":["Rewrite paths as virtual `/`-rooted paths (e.g. `/workspace/file.txt`) and map Windows files into the workspace root","Convert Windows paths programmatically (`PureWindowsPath(...).as_posix()` then relativize against the mount root)","Reject or translate drive-letter paths at your tool/input boundary before invoking the backend","Document the virtual-path convention in agent prompts so the model emits `/`-rooted paths"],"exampleFix":"// before\nbackend.read(r'C:\\Users\\me\\doc.txt')\n// after\nbackend.read('/workspace/doc.txt')  # file mounted/copied under /workspace","handlingStrategy":"validation","validationCode":"import re\nfrom pathlib import PurePosixPath, PureWindowsPath\nWIN_DRIVE = re.compile(r'^[a-zA-Z]:')\ndef to_virtual_path(path: str, mount: str = '/workspace') -> str:\n    if WIN_DRIVE.match(path):\n        posix = PureWindowsPath(path).as_posix().split('/', 1)[-1]\n        return f'{mount}/{posix}'\n    return path\nbackend.read(to_virtual_path(r'C:\\Users\\me\\doc.txt'))","typeGuard":"def is_posix_virtual_path(path: object) -> bool:\n    import re\n    return isinstance(path, str) and not re.match(r'^[a-zA-Z]:', path)","tryCatchPattern":"try:\n    content = backend.read(path)\nexcept ValueError as exc:\n    if 'Windows absolute paths are not supported' in str(exc):\n        content = backend.read(to_virtual_path(path))\n    else:\n        raise","preventionTips":["Translate Windows paths to /-rooted virtual paths at your input boundary","Mount or copy local Windows files under the virtual workspace root","Instruct the agent (system prompt) to always emit /-rooted virtual paths","Run a pre-check for drive-letter prefixes in tool arguments on Windows hosts"],"tags":["path-traversal","windows","validation"],"backgroundTag":"windows-path-not-supported","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}