helm/helm · error

no API version specified

Error message

no API version specified

What it means

ErrNoAPIVersion is the sentinel returned by loadIndex (pkg/repo/v1/index.go:398) when an index.yaml unmarshals successfully but its apiVersion field is not set to the expected v1 API version. Helm requires every repository index to declare its schema version before it can be trusted.

Source

Thrown at pkg/repo/v1/index.go:48

	"strings"
	"time"

	"github.com/Masterminds/semver/v3"
	"sigs.k8s.io/yaml"

	"helm.sh/helm/v4/internal/fileutil"
	"helm.sh/helm/v4/internal/urlutil"
	chart "helm.sh/helm/v4/pkg/chart/v2"
	"helm.sh/helm/v4/pkg/chart/v2/loader"
	"helm.sh/helm/v4/pkg/provenance"
)

// APIVersionV1 is the v1 API version for index and repository files.
const APIVersionV1 = "v1"

var (
	// ErrNoAPIVersion indicates that an API version was not specified.
	ErrNoAPIVersion = errors.New("no API version specified")
	// ErrNoChartVersion indicates that a chart with the given version is not found.
	ErrNoChartVersion = errors.New("no chart version found")
	// ErrNoChartName indicates that a chart with the given name is not found.
	ErrNoChartName = errors.New("no chart name found")
	// ErrEmptyIndexYaml indicates that the content of index.yaml is empty.
	ErrEmptyIndexYaml = errors.New("empty index.yaml file")
)

// ChartVersions is a list of versioned chart references.
// Implements a sorter on Version.
type ChartVersions []*ChartVersion

// Len returns the length.
func (c ChartVersions) Len() int { return len(c) }

// Swap swaps the position of two items in the versions slice.
func (c ChartVersions) Swap(i, j int) { c[i], c[j] = c[j], c[i] }

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Add `apiVersion: v1` (and typically `generated:` and `entries:`) at the top of index.yaml
2. Regenerate the file with `helm repo index ./charts-dir` so the header is always correct
3. If serving via HTTP, fetch the file directly (curl <repo>/index.yaml) to confirm what clients actually receive

Example fix

# before
# index.yaml
entries: {}
# after
apiVersion: v1
entries: {}

raw, err := os.ReadFile(indexPath)
if err != nil { return err }
var probe map[string]any
if err := yaml.Unmarshal(raw, &probe); err != nil { return err }
if _, ok := probe["apiVersion"]; !ok {
    return errors.New("index.yaml is missing apiVersion; add `apiVersion: v1`")
}

if _, err := repo.LoadIndexFile(path); err != nil {
    if errors.Is(err, repo.ErrNoAPIVersion) {
        // fix or regenerate the index, then reload
    }
}

When it happens

Trigger: repo.LoadIndexFile / LoadIndex on an index.yaml missing the `apiVersion: v1` line; hand-authored index files; a repo server that generates an index without the apiVersion key.

Common situations: Manually written index.yaml for a static chart repo; custom index generation scripts that omit the header; truncated or template-rendered index files.

Related errors

• merge failed: %w
• error loading %s: %w
• entry not found
• no chart version found
• no chart name found

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