usestrix/strix · error · ValueError

'{spec}' has a control character in its destination path

Error message

'{spec}' has a control character in its destination path

What it means

Raised by _workspace_file_dest() when the destination path contains a control character (any char with ord < 0x20, or 0x7F DEL). The destination is rendered inline in the agent task text, and a control character could make the path span more than its single rendered line (or smuggle line breaks), so the whole spec is rejected defensively.

Source

Thrown at strix/interface/utils.py:1711

    """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(":")
        source_text = raw if sep and dest.strip() else spec
        source = Path(source_text.strip()).expanduser()
        if not source.is_file():
            raise ValueError(f"'{source}' is not an existing file")

View on GitHub (pinned to 8551339130)

Solutions

  1. Strip/validate control characters before passing specs: ''.join(c for c in dest if ord(c) >= 0x20 and ord(c) != 0x7F)
  2. Fix the upstream data: strip \r\n from lines read from spec files: line.rstrip('\r\n')
  3. Type the destination manually as plain ASCII instead of pasting from formatted text

Example fix

# before
specs = [line for line in open('specs.txt')]  # may carry trailing \r\nstrix --workspace-file specs[0] ...
# after
specs = [line.rstrip('\r\n') for line in open('specs.txt')]
strix --workspace-file specs[0] ...
Defensive patterns

Strategy: validation

Validate before calling

def has_control_chars(s: str) -> bool:
    return any(ord(c) < 0x20 or ord(c) == 0x7F for c in s)

specs = [s for s in raw_specs if not has_control_chars(s)]

Try / catch

try:
    resolve_workspace_files(specs)
except ValueError as e:
    if 'control character' in str(e):
        specs = [clean(s) for s in specs]  # strip and re-run
    else:
        raise

Prevention

When it happens

Trigger: Passing a spec whose DEST contains a newline, tab, escape sequence, or raw byte like \x01: --workspace-file a.txt:bad\nname, or specs read from a file/JSON with embedded escape codes (\r\n line endings) that were never stripped.

Common situations: Specs generated from untrusted or machine-written data (CSV, JSON payloads) containing \r or \n; a terminal paste accident injecting a raw control byte; CI config files with Windows CRLF line endings bleeding into a variable used as DEST.

Related errors

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