usestrix/strix · error · ValueError

'{spec}' has an empty destination path

Error message

'{spec}' has an empty destination path

What it means

Raised by _workspace_file_dest() when the destination component of a --workspace-file spec resolves to an empty string after stripping slashes and the /workspace/ prefix. This means the spec explicitly declared a destination but it contains nothing usable, e.g. 'file.txt:' or ':'.

Source

Thrown at strix/interface/utils.py:1705

# ``--workspace-file`` places a single host file into the sandbox workspace,
# outside every target tree. Content rides the same upload as the target
# 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] = {}

View on GitHub (pinned to 8551339130)

Solutions

  1. Remove the trailing colon so the destination defaults to the file name: --workspace-file notes.txt
  2. If DEST comes from a variable, ensure it is non-empty: --workspace-file "a.txt:${DEST:-a.txt}"
  3. Put an actual relative path after the colon: --workspace-file a.txt:configs/a.txt

Example fix

# before (DEST empty at runtime)
strix --workspace-file "a.txt:$DEST" -t ./
# after
strix --workspace-file "a.txt:${DEST:-a.txt}" -t ./
Defensive patterns

Strategy: validation

Validate before calling

def normalize_spec(spec: str) -> str:
    raw, sep, dest = spec.rpartition(":")
    if sep and not dest.strip():
        return raw  # drop empty ':DEST' tail, default to source name
    return spec

Try / catch

try:
    resolve_workspace_files(specs)
except ValueError as e:
    exit(f"bad --workspace-file spec: {e}")

Prevention

When it happens

Trigger: Passing a spec ending in a bare colon or slashes: --workspace-file notes.txt: or --workspace-file a.txt:/workspace///. After rpartition(':') the dest part is non-empty whitespace or only slashes, which strip to empty and trigger the ValueError.

Common situations: Shell quoting mistake leaves a trailing ':' (e.g. building specs with "${FILE}:${DEST}" where DEST is an unset/empty variable), or a user mimics a PATH:DEST syntax with an intentionally empty DEST thinking it means 'default'.

Related errors

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