vouchfx-mcp GitHub
Documentation / VFX-E-1503

VFX-E-1503

Title

AmbiguousRunInput

Explanation

run_suite takes the suites to run in one of two ways, and exactly one of them must be present: path (a single suite file, the original input shape) or paths (an array of suite files and/or workspace-relative globs, added in run_suite v2). Supplying both, or neither, does not identify a suite set, so nothing is run and the call is refused before any process is spawned.

This is the same rule validate_suite states for its own path/yaml pair (VFX-E-1152), applied to run_suite's own arguments. It carries its own code rather than reusing that one because the argument names — and therefore the fix — differ: a host that reads this code knows the remedy is "drop path or drop paths" without parsing the message.

The two inputs are not interchangeable in one respect worth knowing: glob syntax is expanded only inside paths. A path containing * or ? is treated as a literal file name, exactly as it always has been, and fails as a missing file (VFX-E-1002) if nothing is called that. This keeps every pre-v2 call meaning precisely what it meant before, and it is why the two inputs are kept distinct rather than merged into one that accepts either shape.

Retrying the identical call cannot help — it carries the identical arguments — so this error is not retryable. Send one input or the other.

Common causes

  • Both path and paths were supplied, typically while migrating a caller from the single-path input to the array one.
  • Neither was supplied — for example a host that builds its arguments dynamically and produced an empty object when its path list turned out to be empty.
  • A wrapper that always sends path for compatibility, plus paths when it has more than one suite, without dropping the first.
  • An agent that copied a paths example into a call it had already filled in with path.

Fixes

  • Send exactly one of the two: path for a single suite file, or paths for one or more files and/or workspace-relative globs.
  • When migrating to the array input, delete the path argument rather than leaving it beside paths.
  • If your path list can legitimately be empty, do not call run_suite at all — an empty run has no verdict to report.
  • To run one suite through the new input, pass paths: ["e2e/checkout/happy-path.e2e.yaml"]; the result is identical to passing it as path, plus a per-suite specs[] entry.
  • Remember that a glob only expands inside paths — path: "e2e/**" is a literal file name and will be reported as missing, not expanded.