VFX-E-1505¶

Title¶

RunNotFound

Explanation¶

A tool was asked about a runId that the run registry has no record of. Nothing was read, and no events, status, or artefacts could be reported for it.

The run registry is this server's record of every run run_suite has started. Its reach depends on how the server was launched: with --workspace <path> it is a set of files under that workspace's output directory, so it spans server restarts and previous sessions; without --workspace it lives only in memory, so it holds exactly the runs started since this server process began and is empty again after a restart. A runId from yesterday's session is therefore genuinely unknown to a server started without a workspace — that is the mode's documented behaviour, not a fault.

This is deliberately a different code from VFX-E-1004 (the events file does not exist), because the two are different facts with different remedies. VFX-E-1505 means the server has no record of the run at all — usually a mistyped or stale id. VFX-E-1004 means the record exists and its event stream is gone — usually a cleaned output directory. Collapsing them would make "you used the wrong id" indistinguishable from "your run's artefacts were swept".

Every tool that takes a runId answers this way for the same condition — get_run_events, get_run_status, cancel_run, get_step_timeline and get_run_artifacts — because the fact and the remedy are identical whichever asked. Note in particular what it does not mean for cancel_run: a run that exists but cannot be stopped from this server is VFX-E-1507, and one whose entry is residue from a killed server is VFX-E-1508. This code means the registry has never heard of the id at all.

Retrying the identical call cannot help: the registry gains a run only when a run_suite call starts one, which is a different call. That is why this error is not retryable.

Common causes¶

• The runId was mistyped, truncated, or copied with surrounding punctuation.
• The id came from a previous session and the server was launched without --workspace, so its registry is session-scoped and started empty.
• The run's metadata directory was deleted from the workspace's output directory (for example by a CI cleanup step) after the run finished.
• The server was launched with a different --workspace than the one the run was recorded under.
• An id was invented or reconstructed by hand rather than taken from a run this server actually started.

Fixes¶

• Take the runId from a run this server started, rather than from another machine, another workspace, or an earlier session.
• Launch the server with --workspace <path> if you need run history to survive restarts; without it the registry is session-scoped by design.
• Check that the --workspace this server was launched with is the same one the run was recorded under.
• If the run has genuinely been swept, start a fresh run with run_suite and use the new id.
• If you only need the most recent run's diagnosis rather than a specific one, call explain_run with no arguments — it defaults to the most recent finished run and needs no id at all.
• Call list_runs to see exactly which runs this server knows about, newest first, rather than guessing at an id.