Key problems

TVO-KEY-* covers key material — missing, expired, unwrap failure, rotation, backup and recovery. Exit class 11.

Expired attribute certificate

TVO-KEY-001, the most common and the least alarming.

tovio key statustovio key renew

Your key is fine; its attestation lapsed. key status shows each certificate with its issuer, expiry, and validity, so you can see which one went stale.

key renew re-issues the certificates this identity issued, which is the whole story in a self-KA (team) repository. If your certificates come from a remote Key Authority, renewing your own against it is not yet a local command — the issuer has to re-issue for you. Check key status for the issuer before assuming renew is your fix.

Key not found

TVO-KEY-002 — the material is absent, not stale. Usually a fresh clone before a renew, a new machine, a reinstalled OS, or a keychain that is locked or unreachable.

tovio identity showtovio key import <backup-file> --passphrase-file <file>

Unlock the OS keychain and retry first — that is the fix more often than a restore is.

The backup is for a different identity

TVO-KEY-003. key import checks that the backup’s identity matches this repository’s and fails closed when it does not, so a wrong backup can never silently install an unrelated key. Find the right backup.

Unwrap failure

The key exists but cannot open the content — typically because access was rotated after a revocation, or you are using a key from before a rotation. Confirm with tovio access check <path> and get re-enrolled if needed.

Rotation went wrong

tovio key rotate is crash-resumable, and two codes describe the unhappy paths: TVO-KEY-004 when an interrupted rotation cannot resume, and TVO-KEY-005 when the rotation journal fails verification on a later read. Neither is something to force past — a rotation that cannot prove its own journal is exactly the state that must not be waved through. Bring it to a maintainer.

Headless hosts and CI

No secret service means the wrapped keystore on disk. That is normally automatic, but on a locked-down or headless machine you may need to inject the wrapping key through the TOVIO_KEYSTORE_KEY environment variable. If a CI job cannot find keys, check first that it is not expecting a desktop keychain.

If you lost the key itself

You may not be stuck. Any repository that has a cryptographic identity — one initialized with --mode team or --mode agentic — also generated an independent recovery key at init and enrolled it as an extra recipient of protected content, so there is a path back that does not need your identity key at all. See the recovery article; it is a different command from key import.

Never paste a key

Not a key, not a recovery phrase, not a passphrase file. Not into a ticket, a board, or a chat, however stuck you are. Report the code and what you were doing.