manifest does not contain a layer with mediatype %s

Error message

manifest does not contain a layer with mediatype %s

What it means

The pull requested the chart content (operation.withChart, the default) but no layer in the manifest uses the chart media type application/vnd.cncf.helm.chart.content.v1.tar+gzip (or the legacy application/tar+gzip). The config descriptor exists but the actual chart tarball layer is missing.

Source

Thrown at pkg/registry/client.go:480

		switch d.MediaType {
		case ConfigMediaType:
			configDescriptor = &d
		case ChartLayerMediaType:
			chartDescriptor = &d
		case ProvLayerMediaType:
			provDescriptor = &d
		case LegacyChartLayerMediaType:
			chartDescriptor = &d
			_, _ = fmt.Fprintf(c.out, "Warning: chart media type %s is deprecated\n", LegacyChartLayerMediaType)
		}
	}

	// Chart-specific validation
	if configDescriptor == nil {
		return nil, fmt.Errorf("could not load config with mediatype %s", ConfigMediaType)
	}
	if operation.withChart && chartDescriptor == nil {
		return nil, fmt.Errorf("manifest does not contain a layer with mediatype %s",
			ChartLayerMediaType)
	}

	var provMissing bool
	if operation.withProv && provDescriptor == nil {
		if !operation.ignoreMissingProv {
			return nil, fmt.Errorf("manifest does not contain a layer with mediatype %s",
				ProvLayerMediaType)
		}
		provMissing = true
	}

	// Build chart-specific result
	result := &PullResult{
		Manifest: &DescriptorPullSummary{
			Digest: genericResult.Manifest.Digest.String(),
			Size:   genericResult.Manifest.Size,
		},

View on GitHub (pinned to 2a29f1770b)

Solutions

List the manifest layers (`crane manifest <ref>`) and confirm one has the Helm chart media type
Re-push the chart with `helm push chart.tgz oci://...` to recreate a complete manifest
If building with ORAS, attach the chart tarball with media type application/vnd.cncf.helm.chart.content.v1.tar+gzip

Defensive patterns

Strategy: try-catch

Try / catch

res, err := client.Pull(ref)
if err != nil && strings.Contains(err.Error(), "manifest does not contain a layer with mediatype "+registry.ChartLayerMediaType) {
	// chart layer missing: re-push or fix the producer that builds the manifest
}

Prevention

Do not run registry GC without a grace period longer than your push cadence
When assembling chart manifests by hand, include the tar.gz layer with the Helm chart media type

When it happens

Trigger: Pulling a manifest that has a Helm config but whose chart layer was never attached — interrupted pushes, registry GC deleting the layer, or hand-built manifests that omitted the tarball layer.

Common situations: Registry garbage collection run between push and pull; multi-arch or index artifacts mistakenly pushed under the chart reference; CI tooling assembling manifests manually.

Related errors

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/752f0bbb604aa9b8. Report an issue: GitHub.