## TL;DR

Helm renders values into manifests, so secrets in values end up in plaintext. Reference existing secrets instead of templating values in, and fix render errors by checking the template functions against the values structure.

## Error

```text
helm values failed: secret template render error
```

## Steps

1. Read the render error for the line and function that failed. Expected: the exact template expression.
2. Check the values structure matches what the template expects (nesting, types). Expected: the mismatch found.
3. Move secret values out of values files: use existingSecret references the chart supports. Expected: no secret material in values.
4. Render locally to verify: `helm template` against the chart. Expected: clean manifests.
5. Install or upgrade with the fixed values. Expected: success.

## When to use

- Helm secret template render failures.
- Hardening charts against secret leaks.

## When not to use

- Non-secret template errors (fix the template logic).
- Sealed-secret or external-secret controllers (different flow).

## Tool compatibility

- Helm 3; charts using existingSecret patterns.

## Variant phrasings

### helm template secret render failed

Same values-structure fix.

### secret values not rendering in helm

Check nesting and functions.

## Why it happens

Helm is a templating engine, not a secret manager; values are plaintext by design, and template functions fail on unexpected shapes.

## Edge cases

- `helm template` output can contain secrets; treat its output as sensitive.
- Values from `--set` with special characters need quoting.
- Chart upgrades can change the expected values shape; check the changelog.

## Provenance

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