Troubleshoot "failed to render archive directory" in KOTS

Troubleshooting
,
1

The failed to render archive directory error can appear in the KOTS Admin Console Config Screen or when KOTS is downloading a new app update. This error indicates that KOTS cannot render the upstream manifests with the current config values, which may involve running helm template from upstream releases.

Common Causes

This error typically occurs due to:

  • Incorrect Go template syntax in the application Helm Chart
  • Incorrect mappings from the KOTS HelmChart custom resource
  • Invalid inputs from KOTS Config Values

Diagnosing the Error

When this error occurs, examine the kotsadm pod logs to see detailed templating errors.

Local Reproduction Steps

You can reproduce and debug this issue locally without creating a new release or accessing the KOTS Admin Console:

1. Generate ConfigValues File

Generate a KOTS ConfigValues file following this guide. Use the same values provided in the Admin Console Config Screen when the error occurs.

2. Pull the Application

Run the following command to pull the application and trigger the same rendering process:

kubectl kots pull <app-slug>/<channel> \
  --license-file <license.yaml> \
  --shared-password <random-password> \
  --config-values <config-values.yaml> \
  --downstream this-cluster

The standard output will contain the render error as KOTS performs rendering behind the scenes.

Example error output:

 • Checking for license update ✓  
  • Pulling upstream ✓  
  • Rendering KOTS custom resources ✓  
  • Creating base ✓  
  • Creating midstreams ✓  
  • Creating downstream "this-cluster" ✓  
Error: failed to pull: failed to write rendered: failed to write helm rendered: failed to template helm chart for rendered dir: failed to run helm install: YAML parse error on <path>.yaml: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field .metadata.annotations of type string

3. Examine Generated Files

Even when the command fails, it generates a folder named <app-slug> with the following structure:

.
├── base
│   ├── admin-console
│   └── kustomization.yaml
├── helm
│   └── <chart-name>
├── overlays
│   ├── downstreams
│   └── midstream
├── rendered
│   └── this-cluster
├── skippedFiles
└── upstream
    ├── admin-console
    ├── <multiple-manifests>.yaml
    └── userdata

4. Debug with Helm Template

Focus on the helm folder, which contains:

helm
└── <chart-name>
    ├── <chart-name>-<version>.tgz
    └── values.yaml

The values.yaml file is generated after KOTS maps Config Values to the HelmChart resource. Run helm template against this to pinpoint the issue:

helm template <chart>.tgz -f values.yaml --debug

Example Helm output:

Error: YAML parse error on <chart>/templates/<file>.yaml: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field .metadata.annotations of type string
helm.go:86: 2025-07-01 14:45:31.86323 +1000 AEST m=+0.664205751 [debug] error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field .metadata.annotations of type string

Fixing and Verifying the Solution

Once you’ve identified and fixed the issue in the chart, verify the solution locally using the KOTS CLI before creating a release:

kubectl kots pull <app-slug>/<channel> \
  --license-file license.yaml \
  --shared-password <random-password> \
  --config-values config-values.yaml \
  --downstream this-cluster \
  --local-path <path-to-release-folder>

KOTS will use the local path instead of downloading from upstream. With the fix applied, there should be no errors in the terminal output.

Getting Additional Help

If the issue persists after following this guide, contact Replicated Support and provide:

  • The ConfigValues file
  • The output from the steps taken above
1 Like