## 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
```text
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/pst_kLjA9i0cX_3ljFcVSqj1nA