langchain-ai/deepagents · error · ValueError

Windows absolute paths are not supported: {path}. Please use

Error message

Windows absolute paths are not supported: {path}. Please use virtual paths starting with / (e.g., /workspace/file.txt)

What it means

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.

Source

Thrown at libs/deepagents/deepagents/backends/utils.py:707

        validate_path("foo/bar")  # Returns: "/foo/bar"
        validate_path("/./foo//bar")  # Returns: "/foo/bar"
        validate_path("../etc/passwd")  # Raises ValueError
        validate_path(r"C:\\Users\\file.txt")  # Raises ValueError
        validate_path("/data/file.txt", allowed_prefixes=["/data/"])  # OK
        validate_path("/etc/file.txt", allowed_prefixes=["/data/"])  # Raises ValueError
        ```
    """
    # Check for traversal as a path component (not substring) to avoid
    # false-positive rejection of legitimate filenames like "foo..bar.txt"
    parts = PurePosixPath(to_posix_path(path)).parts
    if ".." in parts or path.startswith("~"):
        msg = f"Path traversal not allowed: {path}"
        raise ValueError(msg)

    # Reject Windows absolute paths (e.g., C:\..., D:/...)
    if re.match(r"^[a-zA-Z]:", path):
        msg = f"Windows absolute paths are not supported: {path}. Please use virtual paths starting with / (e.g., /workspace/file.txt)"
        raise ValueError(msg)

    normalized = os.path.normpath(path)
    normalized = normalized.replace("\\", "/")

    if not normalized.startswith("/"):
        normalized = f"/{normalized}"

    # Defense-in-depth: verify normpath didn't produce traversal
    if ".." in normalized.split("/"):
        msg = f"Path traversal detected after normalization: {path} -> {normalized}"
        raise ValueError(msg)

    if allowed_prefixes is not None and not any(normalized.startswith(prefix) for prefix in allowed_prefixes):
        msg = f"Path must start with one of {allowed_prefixes}: {path}"
        raise ValueError(msg)

    return normalized

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rewrite paths as virtual `/`-rooted paths (e.g. `/workspace/file.txt`) and map Windows files into the workspace root
2. Convert Windows paths programmatically (`PureWindowsPath(...).as_posix()` then relativize against the mount root)
3. Reject or translate drive-letter paths at your tool/input boundary before invoking the backend
4. Document the virtual-path convention in agent prompts so the model emits `/`-rooted paths

Example fix

// before
backend.read(r'C:\Users\me\doc.txt')
// after
backend.read('/workspace/doc.txt')  # file mounted/copied under /workspace

import re
from pathlib import PurePosixPath, PureWindowsPath
WIN_DRIVE = re.compile(r'^[a-zA-Z]:')
def to_virtual_path(path: str, mount: str = '/workspace') -> str:
    if WIN_DRIVE.match(path):
        posix = PureWindowsPath(path).as_posix().split('/', 1)[-1]
        return f'{mount}/{posix}'
    return path
backend.read(to_virtual_path(r'C:\Users\me\doc.txt'))

def is_posix_virtual_path(path: object) -> bool:
    import re
    return isinstance(path, str) and not re.match(r'^[a-zA-Z]:', path)

try:
    content = backend.read(path)
except ValueError as exc:
    if 'Windows absolute paths are not supported' in str(exc):
        content = backend.read(to_virtual_path(path))
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid agent name: {agent_name!r}. Agent names can only con
• Invalid MCP server name {server_name!r}: token storage names
• Error: {path_error}
• Path traversal not allowed: {path}
• Path traversal detected after normalization: {path} -> {norm

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/1a01e6e3349eaf7c. Report an issue: GitHub.