Module management troubleshooting
Read the server’s error code and message alongside the HTTP status. A 409
means the request conflicts with the current state; it does not necessarily
mean you lack permission. Read the current version, catalogue or Pin revision
before deciding whether to retry. For a retry, keep the same Idempotency Key
and request.
| Symptom | Check and next action |
|---|---|
semantic_version is required from old Module creation | Migrate to catalogue identity plus complete immutable version publication. Use the CLI/provider paired with the server release. |
Inline source rejected for artifact_digest | Omit the field. The immutable Module Version already stores inline source. |
| External source has no digest | Omission is valid for new and legacy versions. Keep the exact source revision; do not manufacture a digest. If supplied, it must be canonical sha256:<64 lowercase hex>, nonempty and immutable. |
| Version says Unverified | Expected in this release. Trusted artifact verification is deferred; Unverified does not block otherwise eligible use or promotion. |
| No deployable Default | The Module is empty, its first candidate is not promoted, or the Default was marked Defective. Inspect history and explicitly promote an eligible stable candidate or restore the exact eligible predecessor. |
| Proposed slot occupied | Promote, withdraw (deprecate), or mark the current candidate Defective with a reason. Use atomic stable-successor publication to graduate a prerelease. Waiting does not expire it. |
| Prerelease promotion rejected | Publish a separate higher-precedence stable successor, then promote it. A prerelease cannot become Default. |
| Equal or lower SemVer rejected | Check the current Default, or the most recent Defective Default if none is active. Build metadata does not increase precedence. Publishing a new version cannot downgrade. |
| Lifecycle command conflicts | Refresh the current revision, inspect competing transitions and submit a newly reviewed command. Do not increment an expected revision blindly. |
| Module publication fails Resource Type validation | Correct the complete definition’s interface. If the interface itself must change, use a new Resource Type and Module identity. |
resource_type_contract_invalid | Check the bounded OpenAPI 3.0 subset, supported keywords and limits. No $ref, external loading, defaults or unknown keywords; array schemas require items. |
module_resource_type_nonconformant | Read the definition pointer and failed rule in the redacted diagnostic. Correct the complete input, parameter, provider, dependency or co-provisioned declaration. Placeholders are checked as literal strings without evaluation. |
module_output_declaration_required | Add the author’s explicit output_schema to the new version. A nonempty Resource Type schema requires it even when module_contract is absent. Do not infer it automatically from the Resource Type. |
module_output_contract_mismatch | The declaration must equal the Resource Type output schema as JSON, including constraints and descriptions. Whitespace/key order do not matter; semantically similar but unequal schemas are rejected in this iteration. |
| Archived Module cannot be adopted | Unarchive with appropriate organisation scope and a reason. Existing use and Pins do not authorise adoption by another Environment. |
| Normal deployment rejects Deprecated version | Move to an allowed version or preserve the exact already-active version with an authorised Pin. A Pin cannot choose another historical version. |
| Pin creation rejects current state | Wait for active deployment to settle, or use normal recovery for Unreconciled state. The Pin must refer to the latest trustworthy successful deployment. |
| Unpin returns forbidden | Check module.version.unpin for the exact Environment scope. Being the creator does not grant this permission. |
| Pin is Override Pending | Inspect the operation that owns the override and its Deployment. Finish or cancel through that add-on. Waiting or restarting the process cannot release the lock. |
| Terraform plans repeated lifecycle changes | Inspect configured lifecycle_status on historical versions and changing inputs on lifecycle transaction receipts. Use observed status or explicit reviewed command ownership. |
| Terraform delete reports retained history | Versions are permanent. Archive the catalogue; explicitly retain referenced provider/Resource Type identities. Import retained objects on a later setup. |
| Immutable version missing after a database reset | Investigate database and state provenance. Do not let refresh silently replace lost history. A deliberate disposable reset needs corresponding state handling; it is not a production migration. |
| Module is visible but history, details or comparison are unavailable | Check module.version.read for the same scope. module.read can show the catalogue entry without granting Version history. Show this as unavailable history, not as an empty Module. |
| Console Module pages work internally but fail via API hostname | Verify the release chart routes for catalogue, versions, Pins, lifecycle transactions and capability discovery. A Console-only upgrade cannot supply missing backend routes. |
Runner Job has ImagePullBackOff | Inspect the exact Job image and pull permissions. Check the Runner Job image as well as the gateway image. Public Orchestrator releases should pull anonymously; private candidate images need their own configured credentials. |
In an issue report, include the component versions you are using, the command, resource identities, HTTP status, error code and correlation ID. Remove tokens, private keys, sensitive logs, state contents and Deployment Outputs before sharing. Use history and adoption and migration guidance to distinguish a retained record from an active runtime resource.