Kustomize render failures: mapping key already defined

When saving configuration changes in the KOTS Admin Console configuration screen, you may encounter the following error failed to render archive directory

By inspecting the kotsadm pod logs, you might see an error stack similar to:

rewrite directory: failed to write rendered: failed to write kustomize rendered: failed to render charts archive: failed to walk charts directory: failed to kustomize…
…
yaml: unmarshal errors:
line 15: mapping key “apiVersion” already defined at line 2
line 16: mapping key “kind” already defined at line 3
line 17: mapping key “metadata” already defined at line 4

This occurs when multiple Kubernetes objects are defined in the same YAML file without proper separation, leading to YAML parsing errors.

How to Identify the Problematic File

You can quickly locate files that define multiple top-level resources (e.g., multiple apiVersion entries) using the following command in the app release directory:

ag -c "apiVersion:" | ag -v "\:1"

Example output

/charts/.../deployment.yaml:2
/charts/.../serviceaccount-template.yml:2
/charts/.../system-update-job.yml:2

These results indicate that the file defines more than one object, potentially without the required separation.

Resolution Steps

  • Verify templates: Ensure that templates use the YAML document separator (---) correctly between multiple objects. This separator should be followed by a line break.
  • Separate manifests: Alternatively, consider splitting each resource into its own dedicated YAML file.

Important Note

This issue occurs only with v1beta1 Helm Charts and does not affect v1beta2 Helm Charts.

Migration

To avoid this and similar issues, consider migrating your charts to v1beta2. Refer to the official migration guide: Migrate Existing Installations to HelmChart v2 | Replicated Docs