HKUDS/Vibe-Trading · error · ValueError

Path {p!r} is outside allowed {purpose} roots. {_describe_ro

Error message

Path {p!r} is outside allowed {purpose} roots.
{_describe_roots(roots)}
Set {_ALLOWED_FILE_ROOTS_ENV} to add an import directory. {_ENV_SCOPE_HINT}

What it means

_safe_import_path (backing safe_user_path / safe_document_path) resolves the path and requires it under one of the allowed file roots; otherwise it raises with the list of allowed roots plus a hint to extend them via the allowed-file-roots environment variable.

Source

Thrown at agent/src/tools/path_utils.py:305

        p: User-supplied path. `~` expansion is supported.
        purpose: Human-readable purpose for error messages.

    Returns:
        Absolute resolved path inside an allowed import root.

    Raises:
        ValueError: If `p` is a UNC share or resolves outside all allowed
            import roots.
    """
    _rejects_unc(p)
    resolved = _import_candidate(p)

    roots = allowed_file_roots()
    for root in roots:
        if resolved.is_relative_to(root):
            return resolved

    raise ValueError(
        f"Path {p!r} is outside allowed {purpose} roots.\n"
        f"{_describe_roots(roots)}\n"
        f"Set {_ALLOWED_FILE_ROOTS_ENV} to add an import directory. {_ENV_SCOPE_HINT}"
    )


def safe_user_path(p: str) -> Path:
    """Validate a user-supplied broker/export file path.

    Args:
        p: User-supplied path. `~` expansion is supported.

    Returns:
        Absolute resolved path inside an allowed import root.

    Raises:
        ValueError: If `p` is a UNC share or resolves outside all allowed
            import roots.

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Move the file under an existing allowed root (listed in the error message)
2. Set the allowed-file-roots env var to include the import directory, scoped per the env hint
3. Check the env var in the exact process running the agent

Example fix

# before
safe_user_path("~/my_data/mod.py")
# after
# AGENT_ALLOWED_FILE_ROOTS=/data
tool.execute(file_path="/data/my_data/mod.py")

from agent.src.tools.path_utils import allowed_file_roots
cand = Path(p).expanduser().resolve()
if not any(cand.is_relative_to(r) for r in allowed_file_roots()):
    raise ArgumentError(f"move {p} under an allowed root or set the env var")

def is_importable_path(p: str) -> bool:
    c = Path(p).expanduser().resolve()
    return any(c.is_relative_to(r) for r in allowed_file_roots())

try:
    safe = safe_user_path(module_path)
except ValueError as e:
    if "outside allowed" in str(e):
        configure_file_roots([str(cand.parent)]); safe = safe_user_path(module_path)

When it happens

Trigger: Importing a user module or document from a directory not in allowed_file_roots(), e.g. ~/my_data when only /workspace/data is allowed.

Common situations: Running the agent under systemd/docker where HOME differs, per-user data directories, or forgetting to configure import dirs at deploy time.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• run_dir {p!r} is outside allowed run roots. {_describe_roots
• unknown zoo {v!r}; expected one of {sorted(_VALID_ZOOS)}
• path must start with "/"
• token_issue_path must start with "/"
• {alpha_id}: import failed: {exc}

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/4cf47c035bfb4fbf. Report an issue: GitHub.