ReasonV1 reference

Fail closed, then follow the exact reason.

Every machine-readable reason links to /troubleshooting#<reason_code>. Preserve the exact code and release identity when reporting a defect.

Safe reporting: share only a manually inspected, redacted SupportReportV1 with a synthetic reproduction. Never attach DoctorReportV1, witness or trace data, license keys, entitlements, credentials, environment files, private paths, or proprietary AIR source.

Compatibility and input

`unsupported_platform`

Use the qualified Linux x86-64 target. macOS and Windows may be used for documentation only, not production proving.

`unsupported_profile`

Compare every dependency and proof parameter with the signed compatibility manifest. Do not assume a nearby Plonky3 profile is equivalent.

`unsupported_air_feature`

Remove the unsupported feature or stop. Lookups, buses, permutations, multi-table, preprocessing, periodic columns, recursion, custom fields, and GPUs are outside v1.

`manifest_contract_invalid`

Validate against the schema bundled with the exact release; reject unknown fields and do not silently coerce values.

`unsafe_path`

Keep relative paths under declared roots. Remove traversal, symlinks, devices, and paths that escape the configured boundary.

`input_limit_exceeded`

Reduce the job to the documented row, width, degree, or input-size limit. Do not split into an unsupported multi-table design.

Resource planning

`ram_budget_insufficient`

Increase the configured RAM budget or choose a supported bounded plan before ingestion.

`scratch_budget_insufficient`

Increase the declared scratch budget to the preflight estimate plus required headroom.

`scratch_space_insufficient`

Free local scratch space or select a larger customer-controlled NVMe volume. Preserve at least 10% free-space headroom.

`job_state_exists`

Do not overwrite an existing job directory. Resume it with the owning release or choose a new empty directory.

Resume and checkpoint

`interrupted_resumable`

The interruption is recoverable. Preserve the job directory and run resume with the exact release.

`checkpoint_missing`

Restore the complete owning job directory from your customer-managed backup or restart in a new directory.

`checkpoint_corrupt`

Do not bypass integrity checks. Restore a verified checkpoint or restart; retain a sanitized integrity report for a defect.

`checkpoint_release_mismatch`

Resume with the exact release recorded by the checkpoint. A newer release must never consume it silently.

`job_not_resumable`

The recorded phase cannot be resumed. Preserve diagnostics and start a new job only after confirming inputs are intact.

Verification, activation, and identity

`verification_rejected`

Stop using the proof and preserve the bundle. Any supported-profile ordinary-verifier rejection is a release-freeze condition.

`release_not_activated`

Activate the exact Guard release before disabling network access. Community doctor and verification paths do not require Guard activation.

`license_inactive`

Use the merchant portal to inspect subscription status. Do not send the key to TinyZKP or a public issue.

`license_provider_unavailable`

Retry initial activation later. A provider outage must not interrupt an already activated release or running proof.

`engine_artifact_mismatch`

Stop. Verify the signed channel, checksum, provenance, and exact engine SHA; never substitute a different binary.

`engine_protocol_invalid`

Stop and preserve sanitized stdout/stderr framing. Guard must not guess or repair an invalid engine protocol.

`release_identity_mismatch`

Stop. Align Guard, engine, OCI digest, schemas, compatibility profile, channel manifest, and checkpoint identity.

`internal_error`

Create and inspect a redacted SupportReportV1. If reproducible, open a defect with synthetic inputs and exact release identity.