HKUDS/Vibe-Trading · error · ValueError

run_dir {p!r} is outside allowed run roots. {_describe_roots

Error message

run_dir {p!r} is outside allowed run roots.
{_describe_roots(roots)}
Set {_ALLOWED_RUN_ROOTS_ENV} to add a run directory. {_ENV_SCOPE_HINT}

What it means

safe_run_dir resolves the supplied run_dir and requires it under one of _allowed_run_roots(); otherwise it raises with the allowed roots list and a hint to extend via the allowed-run-roots env var. Called by backtest/verification entry points before any run artifacts are touched.

Source

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

    Args:
        p: User/LLM-supplied run directory. `~` expansion is supported.

    Returns:
        Absolute resolved path inside an allowed run root.

    Raises:
        ValueError: If `p` is a UNC share or resolves outside all allowed run
            roots.
    """
    _rejects_unc(p)
    resolved = Path(p).expanduser().resolve()

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

    raise ValueError(
        f"run_dir {p!r} is outside allowed run roots.\n"
        f"{_describe_roots(roots)}\n"
        f"Set {_ALLOWED_RUN_ROOTS_ENV} to add a run directory. {_ENV_SCOPE_HINT}"
    )


def safe_run_id(run_id: str) -> Path:
    """Resolve a bare run id to an existing allowed run directory.

    Args:
        run_id: Bare run directory name, not a path.

    Returns:
        Existing run directory under one of the allowed run roots.

    Raises:
        ValueError: If the run id is empty, path-shaped, or not found.
    """

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Keep run dirs under the configured runs directory
2. Add the parent directory via the allowed-run-roots env var (e.g. in the agent service unit)
3. Verify with the roots printed in the error message

Example fix

# before
run_dir="/mnt/restore/run-42"
# after
# AGENT_ALLOWED_RUN_ROOTS=/mnt/restore
run_dir="/mnt/restore/run-42"

cand = Path(run_dir).expanduser().resolve()
assert any(cand.is_relative_to(r) for r in _allowed_run_roots()), "run_dir outside allowed run roots"

def is_allowed_run_dir(rd: str) -> bool:
    c = Path(rd).expanduser().resolve()
    return any(c.is_relative_to(r) for r in _allowed_run_roots())

try:
    rd = safe_run_dir(run_dir)
except ValueError as e:
    if "outside allowed run roots" in str(e):
        os.environ["AGENT_ALLOWED_RUN_ROOTS"] = str(Path(run_dir).parent); rd = safe_run_dir(run_dir)

When it happens

Trigger: Passing run_dir=/some/random/dir when /some/random is not an allowed run root; common when pointing at a copied run directory outside the runs tree.

Common situations: Restored/archived runs moved off the standard runs directory, container volume mounts not in defaults, or env var set only in the dev shell.

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 is required to write/edit {file_path!r}, or the path
• Path {p!r} is outside allowed {purpose} roots. {_describe_ro
• path must start with "/"
• token_issue_path must start with "/"
• UNC paths are not allowed: {p!r}

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