usestrix/strix · error · ValueError

'{source}' is not an existing file

Error message

'{source}' is not an existing file

What it means

Raised by resolve_workspace_files() when the SOURCE half of a --workspace-file spec does not point to an existing regular file on the host. Only single readable host files can be injected; directories, missing paths, and special files are rejected before session bring-up.

Source

Thrown at strix/interface/utils.py:1729

        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")
        try:
            with source.open("rb"):
                pass
        except OSError as error:
            raise ValueError(f"Cannot read '{source}': {error}") from error
        workspace_rel = _workspace_file_dest(spec, source)
        if workspace_rel in seen:
            raise ValueError(
                f"Two workspace files target /workspace/{workspace_rel}: "
                f"'{seen[workspace_rel]}' and '{source}'"
            )
        seen[workspace_rel] = str(source)
        resolved.append(
            {
                "source_path": str(source.resolve()),
                "workspace_path": f"/workspace/{workspace_rel}",
            }
        )

View on GitHub (pinned to 8551339130)

Solutions

  1. Verify the path exists and is a file before invoking strix: python -c "import sys,pathlib; sys.exit(0 if pathlib.Path(sys.argv[1]).expanduser().is_file() else 1)" YOURFILE
  2. Use an absolute path for the source to avoid cwd ambiguity: --workspace-file /home/me/notes.txt:notes.txt
  3. If the file is generated by an earlier step, add existence checks to that step or make the step fail loudly before strix runs

Example fix

# before
strix --workspace-file ./out/report.json:report.json -t ./   # out/ not created yet
# after
mkdir -p out && ./generate_report.py && strix --workspace-file "$(pwd)/out/report.json":report.json -t ./
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def existing_file_specs(specs: list[str]) -> list[str]:
    ok = []
    for spec in specs:
        src = spec.rpartition(":")[0] or spec
        p = Path(src.strip()).expanduser()
        if not p.is_file():
            raise FileNotFoundError(f"missing workspace file source: {p}")
        ok.append(spec)
    return ok

Try / catch

try:
    resolve_workspace_files(specs)
except ValueError as e:
    if 'is not an existing file' in str(e):
        prompt_user_for_correct_path()
    else:
        raise

Prevention

When it happens

Trigger: Passing --workspace-file ./missing.txt, pointing at a directory (--workspace-file ./configs), or a path with a typo. Path.expanduser() is applied, so '~/notes.txt' works but '~otheruser/x' fails if unreadable. The is_file() check runs before any container starts, so this fails fast at CLI argument resolution.

Common situations: Relative path given from a different working directory than expected; file created by an earlier pipeline step that was skipped or failed; spec built from a variable that is empty, making source_text resolve to '.' (a directory).

Related errors

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