vouchfx-mcp GitHub
Documentation / VFX-D-1100

VFX-D-1100

Title

SuiteInvalid

Explanation

run_suite's pre-flight envelope: the suite failed validate_suite's own checks, so run_suite did not run it. This is a successful call (isError: false) — an invalid suite is data, not a tool failure — and this code itself carries no finding of its own; the specific findings (VFX-D-1101 through VFX-D-1105, VFX-D-1107, VFX-D-1201) travel inside the result's validation.errors array. An MCP client keying off isError never sees an invalid suite as a tool failure.

The pre-flight is all-or-nothing across every suite a call names, and it reports every suite it found invalid — invalidSuites[] carries one { path, errors, omittedErrorCount } entry per invalid suite, so repairing a glob takes one call rather than one call per broken file. path and validation describe the first of those entries and are retained for hosts written against the earlier shape. Both lists are bounded with their omissions counted: at most 25 suites and 10 findings per suite, with omittedInvalidSuiteCount/omittedErrorCount saying how much is not shown.

Entries are determined-invalid suites only. A suite whose validity could not be determined at all — missing, unreadable, outside the workspace, or a validation worker that timed out or failed — is not an entry here; when it is the first such suite the whole call is the matching VFX-E-… tool error instead, and when an earlier invalid suite already put the call on this payload it is counted in undeterminedSuiteCount. That count is deliberately separate from omittedInvalidSuiteCount: one means "known invalid, not described here", the other "could not tell".

Common causes

  • The suite has one or more JSON Schema violations (VFX-D-1101).
  • The suite's YAML could not be parsed (VFX-D-1102).
  • The suite file exceeds the YAML-bomb guard's size, nesting, anchor/alias, or per-line-length limits (VFX-D-1103-VFX-D-1105, VFX-D-1107).
  • The suite references a step type the pinned engine does not bundle (VFX-D-1201). From engine v1.2.0 that includes a type supplied by a trusted external provider, which the pre-flight cannot validate even when the engine has loaded the provider; run such a suite with vouchfx run.

Fixes

  • Inspect invalidSuites[] — each entry names one suite and its findings — and consult each finding code's own catalogue page. Fix them all before re-running; one invalid suite refuses the whole call.
  • If omittedInvalidSuiteCount is non-zero, more suites are invalid than the response describes; repair the listed ones and call again to see the rest. One case needs different handling: when invalidSuites is empty and the count is non-zero, nothing was listed because the first suite's own findings filled the whole response — they are all in validation, so repair what that shows first. Re-calling unchanged would return the same answer.
  • If undeterminedSuiteCount is non-zero, some suites could not be checked at all; repair the listed ones and call again, and the next call names the first of them with its own VFX-E-… code.
  • Call validate_suite directly to get the same diagnosis without attempting a run.
  • Re-run run_suite once validate_suite reports valid: true for the same file.