What causes "unable to add helm chart %s to index: %w" in rancher/rancher?

Pull the layer and verify locally: helm show chart on the extracted tar

unable to add helm chart %s to index: %w

Error message

unable to add helm chart %s to index: %w

What it means

fetchChart downloaded the chart tar, but addToIndex failed: loader.Load could not parse the temp file as a Helm chart archive, digestFile failed to hash it, or indexFile.MustAdd rejected the entry. The layer bytes with the Helm media type are not actually a valid chart tarball.

Source

Thrown at pkg/catalogv2/oci/oci.go:356

			return
		}
	}

	// Make sure to convert + to _ since OCI registries do not support + in tags and Helm converts it to _ while fetching the chart.
	originalTag := ociClient.tag
	ociClient.tag = strings.ReplaceAll(ociClient.tag, "+", "_")

	// Fetch the helm chart tar to get the Chart.yaml
	filePath, err = ociClient.fetchChart(orasRepository)
	if err != nil {
		err = fmt.Errorf("failed to fetch the helm chart %s: %w", ociURL, err)
		return
	}

	// Add the chart to the index
	err = ociClient.addToIndex(indexFile, filePath)
	if err != nil {
		err = fmt.Errorf("unable to add helm chart %s to index: %w", ociURL, err)
	}

	// Replace it back so that further comparisons can continue
	ociClient.tag = originalTag

	// Remove the entry from the indexfile since the next function addToIndex
	// will add. This is done to avoid duplication.
	for index, entry := range indexFile.Entries[chartName] {
		if entry.Metadata.Name == chartName && entry.Version == ociClient.tag && entry.Digest == "" {
			indexFile.Entries[chartName] = append(indexFile.Entries[chartName][:index], indexFile.Entries[chartName][index+1:]...)
		}
	}

	// We load index into memory and so we should set a limit
	// to the size of the index file that is being created.
	indexFileBytes, err = json.Marshal(indexFile)
	if err != nil {
		return

View on GitHub (pinned to 932558d4e6)

Solutions

Pull the layer and verify locally: helm show chart on the extracted tar
Re-package with helm package and re-push with helm push
Check disk space for the temp files (os.CreateTemp target)
If digestFile failed, check filesystem health of the rancher pod

Defensive patterns

Strategy: try-catch

Validate before calling

// validate the tar locally before it enters the index
if _, err := loader.Load(chartTarPath); err != nil {
	return fmt.Errorf("not a valid helm chart archive: %w", err)
}

Try / catch

if err != nil {
	if strings.Contains(err.Error(), "failed to load the chart") {
		// the downloaded layer is not a chart tarball: re-push with helm package/push
	} else {
		return err
	}
}

Prevention

Package charts with helm package, never raw tar
Verify chart archives in CI with helm lint / helm show chart
Watch /tmp disk space where chart tars are staged

When it happens

Trigger: A layer labeled application/vnd.cncf.helm.chart.content.v1.tar+gzip whose content is not a Helm chart archive; corrupted or truncated push; unreadable temp file (disk pressure).

Common situations: Hand-crafted artifacts with Helm media types wrapping arbitrary tars; interrupted pushes; full /tmp on the rancher pod.

Related errors

AI-assisted analysis of rancher/rancher@932558d4e6 (2026-08-16). Data as JSON: /api/errors/04556c712604231a. Report an issue: GitHub.