usestrix/strix · error · ValueError

'{spec}' has an invalid destination path: {candidate}

Error message

'{spec}' has an invalid destination path: {candidate}

What it means

Raised by _workspace_file_dest() when the destination path contains an empty, '.' or '..' path component after normalization. This blocks path-traversal: the injected file must stay inside /workspace and cannot climb out or reference the current directory.

Source

Thrown at strix/interface/utils.py:1707

# sources, so a large file makes session bring-up slower.


def _workspace_file_dest(spec: str, source: Path) -> str:
    """Return the workspace-relative destination declared by ``spec``."""
    _, sep, dest = spec.rpartition(":")
    candidate = dest.strip() if sep and dest.strip() else source.name
    if candidate.startswith("/") or Path(candidate).is_absolute():
        if not candidate.startswith("/workspace/"):
            raise ValueError(
                f"'{spec}' must land inside the workspace: use a relative "
                "destination or a path under /workspace"
            )
        candidate = candidate.removeprefix("/workspace/")
    candidate = candidate.strip("/")
    if not candidate:
        raise ValueError(f"'{spec}' has an empty destination path")
    if any(part in ("", ".", "..") for part in candidate.split("/")):
        raise ValueError(f"'{spec}' has an invalid destination path: {candidate}")
    # A control character would let the path span more than the one line it is
    # rendered on in the agent task, so the whole spec is rejected.
    if any(ord(char) < 0x20 or ord(char) == 0x7F for char in candidate):
        raise ValueError(f"'{spec}' has a control character in its destination path")
    return candidate


def resolve_workspace_files(specs: list[str] | None) -> list[dict[str, str]]:
    """Validate ``PATH[:DEST]`` specs into source/destination pairs.

    Each spec names a readable host file. ``DEST`` is the path inside
    ``/workspace``; it defaults to the file name. Raises ``ValueError`` with a
    user-facing message when a spec is unusable.
    """
    resolved: list[dict[str, str]] = []
    seen: dict[str, str] = {}
    for spec in specs or []:
        raw, sep, dest = spec.rpartition(":")

View on GitHub (pinned to 8551339130)

Solutions

  1. Use a clean relative path with no '.', '..' or doubled slashes: --workspace-file a.txt:configs/app.yaml
  2. Normalize generated specs before passing them: posixpath.normpath(dest).replace('./', '') and reject results starting with '..'
  3. For paths that must sit 'up' a level, restructure so all injected files live flat or in subdirs under /workspace

Example fix

# before
strix --workspace-file app.ini:./config/../app.ini -t ./
# after
strix --workspace-file app.ini:app.ini -t ./
Defensive patterns

Strategy: validation

Validate before calling

import posixpath

def clean_dest(dest: str) -> str:
    d = dest.strip().removeprefix("/workspace/").strip("/")
    parts = d.split("/")
    if any(p in ("", ".", "..") for p in parts):
        raise ValueError(f"unsafe destination: {dest!r}")
    return "/".join(parts)

Try / catch

try:
    resolve_workspace_files(specs)
except ValueError as e:
    # message names the offending spec and candidate path
    show_error(str(e))

Prevention

When it happens

Trigger: Specs like --workspace-file a.txt:../escape.txt, --workspace-file a.txt:foo/../bar, --workspace-file a.txt:./a.txt, or a.txt:foo//bar (empty part between slashes). The check runs on candidate.split('/'), so any traversal or duplicate-slash segment raises ValueError.

Common situations: User copies a relative path that was meaningful on the host (./configs/app.yaml) or relies on '..' to place the file next to another workspace dir. Also occurs when specs are generated by joining paths without normalizing (dir + '/' + name producing '//').

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/2ff0f6131db92cc5. Report an issue: GitHub.