sops: failed to decrypt" age key error
Fixes sops 'failed to decrypt' with an age key error: match the age recipient to the key you hold. Use when sops cannot decrypt a file it should open. Not for PGP-key setups.
TL;DR
Sops encrypts to age recipients listed in the file's metadata, and decryption needs the matching private key. Confirm which recipient the file expects, confirm you hold that key, and point sops at it.
Error
"sops: failed to decrypt" age key errorSteps
- Inspect the file header for the age recipients it was encrypted to. Expected: the recipient list.
- Compare against the public key derived from your private age key. Expected: a match, or the realization you hold the wrong key.
- Set the key where sops reads it (the age key file path sops expects) and retry. Expected: decryption succeeds.
- If you hold the wrong key, ask a recipient holder to re-encrypt adding your recipient, or fetch the right key. Expected: the file gains your recipient.
- In CI, confirm the key is present in the job environment before sops runs. Expected: CI decrypts.
When to use
- Sops age decryption fails locally or in CI.
- After recipient changes or key rotations.
When not to use
- PGP-based sops setups (different key handling).
- Corrupt files (different error).
Tool compatibility
- Sops with age; file headers carry recipient metadata.
Variant phrasings
sops no age key found
The key file is missing or mispathed.
sops age decryption failed in CI
Key not injected into the job.
Why it happens
Age is recipient-based: only listed recipients can decrypt. Key rotations and new teammates break the mapping silently.
Edge cases
- Multiple recipients: the file may list several; you need just one matching key.
- Keys with passphrases need an agent; non-interactive CI cannot prompt.
- Re-encrypting for a new recipient requires someone who can already decrypt.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_cjahZCZ7zBX19Se7XAyWjw