VFX-E-1152¶

Title¶

AmbiguousSuiteInput

Explanation¶

validate_suite accepts the suite to check in one of two ways — path, naming a .e2e.yaml file on disk, or yaml, carrying the suite's text directly — and it requires exactly one of them. This code is returned when a call supplies both, or neither.

It is an error rather than a diagnostic because nothing was validated: with both arguments present the server cannot know which suite you meant, and with neither there is no suite at all. Either way no verdict was reached, so there is nothing to return as data.

The same code covers both shapes deliberately — they are one condition ("this call does not identify exactly one suite") with one remedy ("supply exactly one"). The error's message says which of the two you hit.

Note that "supplied" means "present", not "non-empty". Sending path: "" counts as supplying a path; the call proceeds and fails later with VFX-E-1002 (SuiteFileNotFound) instead. That is deliberate: the server does not reinterpret an argument you wrote as one you omitted. A JSON null, by contrast, is not a supplied value — it deserialises to an absent argument, so path: null with a yaml present is an ordinary, successful inline call.

A third, much rarer shape shares this code: a path of exactly --yaml-stdin. That literal string is the marker the server writes in the path position to tell its isolated validation worker "the suite text is arriving on stdin", so a file with that exact name would never be opened — you would get a verdict about an empty document instead of about your file. The server refuses the call rather than answering the wrong question. Any qualified form of the same path (./--yaml-stdin, suites/--yaml-stdin) is unambiguous and works normally.

Common causes¶

• Filling in both fields of a form or template that offers path and yaml side by side, rather than choosing one.
• Calling validate_suite with no arguments at all — for example to "just check the last suite", which this tool does not do (it holds no session state).
• A host or agent that sends every declared parameter, including the ones it left blank, and so emits path and yaml together.
• Sending yaml to validate a draft while a previous call's path argument is still populated in the request being reused.
• Passing the literal --yaml-stdin as a path — either as a real (if oddly named) file, or because a command line was assembled wrongly and a flag ended up in the path position.

Fixes¶

• Drop one of the two arguments. Use path for a suite that exists on disk, and yaml for suite text you have drafted but not written to a file.
• If you want to validate a draft without touching the filesystem, send only yaml — this server is read-only and will never write your draft anywhere.
• If your client always sends both keys, omit the unused one — or send it as null, which counts as absent. An empty string does not: path: "" is a supplied path and fails later as VFX-E-1002.
• If you hit the --yaml-stdin collision, qualify the path (./--yaml-stdin), rename the file, or send its text as yaml.
• Check the error's message: it states whether both were supplied or neither, so you know which correction to make.