Skip to content

Error codes

The stable, append-only error codes every SourceOrrery backend, SDK and the CLI report, generated from the SecretError type in sourceorrery-core.

5 min read

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 1 and, in --output json mode, prints {"error":{"code":"…","message":"…"}} on stderr.
  • Audit rows record the code in their detail column, 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).