Errors and diagnostics

CadFlow reports failure in two forms. Exceptions stop a call whose contract cannot be completed. Structured diagnostics describe preflight, validation, solver, or analysis state that callers may inspect and recover from.

Exception boundary

Failure class	Typical cause	Caller action
ValueError	Invalid range, vector, enum value, incompatible session, or malformed domain state	Correct inputs; do not retry unchanged
TypeError	Unsupported Python type or call shape	Fix the call site or schema conversion
NativeError	Native library loading or C ABI operation failure	Inspect the message, operation, environment, and input geometry
FileNotFoundError / OSError	Missing input, denied path, or external I/O failure	Correct or provision the path
Domain exception	Schema, scene contract, flexible native conversion, or replay-specific failure	Use the domain validation report and exception page

Catch the narrowest exception you can repair. Avoid except Exception around an entire modeling pipeline because it erases the operation boundary and often discards useful diagnostics.

Structured diagnostics

Diagnostic contains:

Field	Meaning
severity	Machine-branchable level, commonly error, warning, or informational
code	Stable diagnostic key for tests and automated recovery
message	Human-readable explanation
hint	Optional corrective action
data	Additional JSON-safe evidence

Branch on code, not on the prose in message.

OperationReport records the operation, status, output metadata, diagnostics, and normalized parameters. Its ok property is the supported success predicate. OperationResult pairs a returned value with that report.

result = model.apply("fillet", body, radius=2.0, edges=(0, 4))
if not result.report.ok:
    for item in result.report.diagnostics:
        print(item.code, item.message, item.hint)
else:
    body = result.value

Preflight versus execution

Model.preflight(operation, *args, **kwargs) checks recognized operations, required arguments, common agent mistakes, and capability state without executing native geometry. Model.apply(...) performs preflight and then executes, returning the value and report together.

Preflight is not a geometric proof. Native construction, topology, file I/O, or solver execution can still fail after a ready report.

Validation reports

Validation is domain-specific:

• Shape.validate() checks inexpensive native measurements and topology state.
• sketch inspection reports solved, underconstrained, or failed constraint state;
• assembly reports expose residuals and unsatisfied constraints;
• physical and simulation reports contain typed issues and cross-reference checks;
• Scene validation checks manifests, resources, schemas, limits, and package structure.

Use non-strict validation while collecting repair evidence. Use strict replay or strict lowering at release boundaries where invalid state must halt the pipeline.

Recovery pattern

1. Validate external schemas before constructing domain objects.
2. Run capability checks and preflight when the operation is dynamic.
3. Execute one bounded operation.
4. Preserve its diagnostic code, normalized parameters, and relevant artifact path.
5. Repair only errors the caller understands; surface the rest with the original cause.
6. Revalidate the final geometry or package independently of intermediate success.