Diagnostics and search outcomes

BGI reports a diagnostic with a stable code, a path to the input or operation, and a human-readable message. In normal text mode it appears on standard error as CODE at path: message. With --json, supported commands return a versioned envelope:

{"schema_version":1,"error":{"code":"CLI_USAGE","path":"argv","message":"..."}}

Start with the path: argv means command syntax or option placement; a YAML path points toward the field to fix. Run bgi validate FILE before solve or build, then bgi config FILE --resolved if material values are suspect. JSON Schema alone does not check all cross-references, dimensions, and constructed geometry.

Exit status	Meaning in the current CLI
0	Command succeeded; for solve, at least one candidate was written.
2	Default status for a user-facing Diagnostic, including invalid input and usage.
3	solve completed its report with no candidates. Read its outcome, termination, and attempt count.
5	Bundle or output-path error, including a missing manifest-listed file in bundle-check or an existing build destination.
70	An unexpected internal error occurred.

A zero-candidate automatic search can mean the declared constraints are infeasible within the searched patterns, or the attempt budget ended before finding a candidate. Inspect the solver report before deciding which. A saved solution is checked against the project when built; stale or altered input can invalidate it. SOLUTION_REQUIRED tells you an automatic build needs --solution.

For the versioned error shape, download the diagnostic schema. The automatic layout guide shows how to inspect a search report, and the CLI reference lists the commands.