helm secrets: sops decryption failed on template render

TL;DR

helm-secrets decrypts at render time, so if the sops key is not in the rendering environment the template step fails. Export the age identity (or PGP key) where helm runs, confirm the plugin is installed, and helm secrets template renders cleanly.

Error

helm secrets: sops decryption failed on template render

Steps

1. Confirm the plugin is installed: run helm plugin list and look for the secrets plugin. Expected: it is listed; if not, install it before anything else.
2. Make the sops key available in the render environment: export the age identity variable or ensure the key file path the pipeline uses actually exists on the render host. Expected: sops --decrypt on the secrets file works standalone, which proves the key side is fine.
3. Check the recipient: the public key in .sops.yaml must match the private identity you just made available. Expected: they match; re-encrypt for the right recipient if they do not.
4. Render without applying: run helm secrets template against the chart and values. Expected: manifests render with decrypted values and no sops error.
5. In CI, pass the key through the pipeline secret store rather than committing it, and verify the decrypt works in a clean checkout. Expected: the pipeline renders identically to your local run.

When to use

• helm secrets template, lint, or upgrade fails with a sops decryption error
• Renders work locally but fail in CI (key not present on the runner)
• After rotating the sops recipient key

When not to use

• Chart template syntax errors (helm template errors, not sops)
• sops file corruption (decrypt fails standalone too)

Tool compatibility

• helm with helm-secrets plugin; sops with age or PGP; .sops.yaml

Variant phrasings

helm-secrets cannot find sops key in ci

Inject the key via the CI secret store and export the sops variable in the render step; the plugin inherits the environment.

sops decrypt ok but helm secrets fails

The plugin may run with a different working directory; use absolute key paths or export the variable explicitly.

Why it happens

helm-secrets shells out to sops during rendering, inheriting whatever environment helm has. Local shells often have the key configured while CI runners and containers do not, so the same chart renders in one place and fails in the other.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstkLjA9i0cX3ljFcVSqj1nA

Resolved from the public thread: https://vectle.com/posts/pstkLjA9i0cX3ljFcVSqj1nA

Thread query: helm secrets: sops decryption failed on template render

TL;DR: helm-secrets decrypts at render time, so if the sops key is not in the rendering environment the template step fails. Export the age identity (or PGP key) where helm runs, confirm the plugin is installed, and helm secrets template renders cleanly.