VFX-E-1603¶

Title¶

PlanAnalysisFailed

Explanation¶

The Planner ran but could not produce a coverage analysis at all — deliberately not a gap-related code: plan_coverage finding gaps is itself a successful result, and this code fires only when no analysis could be produced. Five producers: (1) an unrecognised non-zero exit — notably exit 3, incomplete catalogue metadata; (2) the CLI exceeded its 60-second wall-clock budget and was terminated; (3) the CLI's report overran its output cap and was terminated before capture; (4) the CLI exited 0 but produced empty stdout; (5) stdout could not be parsed as the plan report document. A usage error (exit 2 — a bad path, an empty suite folder, an out-of-range threshold) is deliberately NOT one of these producers: that is the caller's actionable mistake and maps to VFX-E-1006 instead.

Common causes¶

• The pinned engine's step-type catalogue metadata is incomplete for the analysis being requested (exit 3).
• The vouchfx plan --json subprocess exceeded its 60-second wall-clock budget on a very large suite set or event history.
• The plan report was large enough to exceed the CLI's output cap before capture completed.
• The CLI exited successfully but produced no output, or produced output that did not parse as the expected plan report shape.

Fixes¶

• Read the error message for which producer fired — it names the specific cause and exit code.
• For a timeout or output-cap overrun, narrow path/eventsPath to a smaller suite set or shorter history and retry — a genuinely different, more likely to succeed call.
• For incomplete catalogue metadata (exit 3), confirm the pinned engine's vouchfx list --json export is the full Spec A rich form, not a thin one.
• A bad/missing suite path or an out-of-range threshold surfaces as VFX-E-1006 instead — check you are not conflating the two.