Error codes
The stable, append-only error codes every SourceOrrery backend, SDK and the CLI report, generated from the SecretError type in sourceorrery-core.
Every failure a secret operation can report maps to one stable, snake_case
code. Codes are a compatibility contract: they are append-only, never
renamed and never reused. Messages are for humans and may change.
Where you meet them:
- The CLI exits with status
1and, in--output jsonmode, prints{"error":{"code":"…","message":"…"}}on stderr. - Audit rows record the code in their
detailcolumn, never a value. - SDKs map codes to typed errors, each carrying a hint that says what to do.
Messages carry names, versions and timestamps only. No error ever contains a secret value.
| Code | Meaning | Message format | Retry later? |
|---|---|---|---|
not_found |
The named secret does not exist (and is not in the deleted state). | secret '{name}' was not found |
|
version_not_found |
The secret exists but the requested version does not. | version '{version}' of secret '{name}' was not found |
|
deleted |
The secret has been soft-deleted and must be recovered before use. | secret '{name}' is deleted; recover it before use |
|
deleted_conflict |
A soft-deleted secret with this name blocks creating a new one. | a deleted secret named '{name}' exists; recover or purge it first |
|
not_deleted |
Recovery or purge was requested for a secret that is not deleted. | secret '{name}' is not in the deleted state |
|
disabled |
The version is disabled by policy. | secret '{name}' version '{version}' is disabled |
|
not_yet_valid |
The version’s activation time has not been reached. | secret '{name}' version '{version}' is not valid before {not_before} |
|
expired |
The version’s expiry time has passed. | secret '{name}' version '{version}' expired on {expires_on} |
|
invalid_name |
The name does not satisfy the naming rules. | invalid name '{name}': {reason} |
|
invalid_argument |
A caller-supplied argument was rejected. | invalid argument: {0} |
|
permission_denied |
The caller is authenticated but not authorised. | permission denied: {0} |
|
locked |
The vault could not be opened (no key for this machine, a wrong recovery key, …). | vault is locked: {0} |
|
vault_not_found |
The vault does not exist. | vault '{name}' was not found |
|
vault_exists |
A vault with this name already exists. | vault '{name}' already exists |
|
manifest |
A project manifest could not be read or is invalid. | manifest error: {0} |
|
crypto |
A cryptographic operation failed (authentication failure, bad key, …). | cryptographic failure: {0} |
|
storage |
The storage backend failed. | storage failure: {0} |
|
io |
An I/O operation failed. | i/o failure: {0} |
|
unsupported |
The backend does not implement this operation. | unsupported operation: {0} |
|
migration_required |
The vault file was written by an earlier release, in an on-disk format this release does not read. There is no migration: the format changed with how a vault is opened and checked, so the vault is recreated (the code keeps its old name; codes are append-only). The file is left as it is, for the release that wrote it. | vault '{name}' was written by an earlier release (schema {schema}); this release cannot read it and has not changed it: keep the file for that release by moving it out of the vaults folder, then recreate the vault with sourceorrery setup and set its secrets from the old file (the Upgrading guide) |
|
vault_mismatch |
The file found for the requested vault holds a different vault: it was renamed or copied from that vault, or swapped in by someone who can write the vault directory. Refused so that a vault is never served under another vault’s name. | the file for vault '{requested}' holds the vault '{found}' |
|
backup_passphrase |
The passphrase did not open an encrypted backup file. No operation produces it since vault export replaced backups (ADR 0009); it stays because codes are never taken back. |
the passphrase does not open this backup |
|
backup_format |
A backup file was written in a newer format than the build read. No operation produces it since vault export replaced backups (ADR 0009); it stays because codes are never taken back. |
backup format {version} is newer than this build understands; upgrade sourceorrery |
|
unauthenticated |
A remote provider has no credentials for this process, or they have expired. reason is the provider’s own description of what is missing: never a credential, nor any part of one. |
not authenticated to {provider}: {reason} |
|
provider_unavailable |
A remote provider could not be reached or answered with a server error. Transient: the same call may succeed later. | {provider} is unavailable: {reason} |
|
rotation |
A rotation step was asked for in a state that does not allow it: a validated candidate is already waiting, there is nothing to activate or retire, or the grace period has not ended. The message carries versions and times only. | rotation of '{name}': {reason} |
|
outcome_unknown |
A change was sent to a remote provider and whether the provider made it is not known: its answer was lost, it failed in a way that does not prove nothing changed, or the provider made it and the vault could not record it (ADR 0011). Not transient: check the secret at the provider before repeating the change. at names the provider or the vault’s connection; reason says what is known, never a value. |
the change may have been made at {at}: {reason} |
Retry later marks codes for which SecretError::is_transient is true:
calling again later could succeed without administrative action.
Source of truth: crates/sourceorrery-core/src/error.rs (opens in a new tab).