Helm Upgrade Failed: [apiVersion not set, kind not set]

Troubleshooting
1

Problem

Your application update may fail to install with the following error:

Error: UPGRADE FAILED: error validating "": error validating data: [apiVersion not set, kind not set]

This error occurs when one or more Helm templates render empty Kubernetes resources with missing apiVersion or kind fields. This is typically caused by incorrect Helm templating logic, such as conditional blocks that don’t properly handle edge cases.

Diagnosis Steps

1. Reproduce the Issue Locally

First, verify that the error is reproducible outside of the cluster:

helm template <your-chart> -f values.yaml --validate

2. Identify Empty Resources

Use yq to filter and locate resources with missing required fields:

helm template <your-chart> -f values.yaml | yq 'select(.apiVersion == null or .kind == null) | {"index": document_index, "content": .}'

This command identifies any resources missing apiVersion or kind and returns their document index within the rendered template output.

Example output:

---
index: 331
content:
  # commented content

If this command returns data, you’ve confirmed the issue and identified the location of the problematic resource.

3. Locate the Source Template

Use the document index to examine surrounding resources and identify the source template:

helm template <your-chart> -f values.yaml | yq 'select(document_index == 332)'

Example output:

# Source: charts/.../templates/resource.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-cert

The # Source: comment indicates which template file is generating the resources near the problematic index.

4. Review the Full Template Output

For a complete view of all rendered resources:

helm template <your-chart> -f values.yaml | less

Use this to navigate through the output and examine the context around the problematic resource.

Resolution

Navigate to the identified template file (e.g., charts/.../templates/resource.yaml) and review the templating logic. Common causes include:

  • Conditional blocks ({{- if ... }}) that can result in empty YAML documents
  • Missing template guards around optional resources
  • Incorrect indentation in template conditionals

Fix the template logic to ensure resources are either properly rendered with all required fields or completely omitted when conditions aren’t met.

After making corrections, verify the fix by re-running the validation:

helm template <your-chart> -f values.yaml --validate

Create another Replicated release and verify that the chart can be upgraded.

1 Like