VFX-E-1509¶

Title¶

SpecPathNotInRun

Explanation¶

get_step_timeline was given a specPath that is not one of the suites the named run actually covered. The run exists and the argument is well formed — it just names a different suite.

A run records its suite set once, when it starts, and never rewrites it. A single-suite run_suite call records one path; a multi-suite call (paths, or a glob that expanded to several) records every concrete file the expansion selected, resolved to an absolute, workspace-rebased path. get_run_status reports that set as specPaths, and it is the list this check compares against.

The comparison is generous about spelling and strict about membership. A relative path is resolved against the workspace root first, both sides are normalised to full paths, and the match follows the platform's own file-name rules (case-insensitive on Windows, case-sensitive elsewhere) — so you do not have to reproduce the exact string the registry stored. What it will not do is guess: a path that resolves to a file the run never touched is refused rather than answered.

The check is deliberately about the run, not about the filesystem. A suite deleted or moved since the run finished is still a suite that run covered, and get_step_timeline still answers for it. That is why this is not VFX-E-1002 SuiteFileNotFound: the file may exist and be perfectly valid, and the remedy is to name a suite this run covered rather than to go and check a path.

This error is not retryable — a run's suite set is fixed, so the identical call reports the identical thing until you change the argument.

Note that for a run covering several suites, specPath is validated but cannot filter: the engine's event stream carries no per-suite attribution, so the timeline that comes back is the run-wide one for that step id. The result's specPathAttributed field is false in exactly that case, and the conclusion says so in words.

Common causes¶

• The specPath belongs to a different run — an earlier one, or a sibling run started from the same workspace.
• A glob was passed to run_suite and the file you have in mind was not among the ones it actually selected; run_suite's own result lists the resolved paths under specs[].path.
• The path was typed or assembled by hand rather than copied from get_run_status, and points at a suite that exists but was not part of this run.
• The server is running without --workspace, so a relative path was not rebased and resolved against the process's current directory instead of the workspace root.

Fixes¶

• Call get_run_status with the same runId and pass one of the paths it reports under specPaths.
• If you meant a different run, call list_runs to find its runId first — the timeline you want may be in another run entirely.
• If the run covered several suites, remember that any one of its specPaths is accepted and none of them narrows the timeline; check specPathAttributed on the result to see whether attribution was possible.
• Launch the server with --workspace <path> if you want relative suite paths to resolve against a known root rather than against the process's working directory.