helm/helm · error

apiVersion is required. The value must be "v3"

Error message

apiVersion is required. The value must be "v3"

What it means

Thrown by literalParser.listItem (pkg/strvals/literal_parser.go:216) when parsing the second index of a nested list expression like a[0][1]=v. The inner keyIndex() call fails — typically strconv.Atoi cannot convert the text between '[' and ']' (non-numeric, empty, or containing more delimiters) — and the error is wrapped as 'error parsing index'.

Source

Thrown at internal/chart/v3/lint/rules/chartfile.go:128

		return fmt.Errorf("failed to strictly parse chart metadata file\n\t%w", chartFileError)
	}
	return nil
}

func validateChartName(cf *chart.Metadata) error {
	if cf.Name == "" {
		return errors.New("name is required")
	}
	name := filepath.Base(cf.Name)
	if name != cf.Name {
		return fmt.Errorf("chart name %q is invalid", cf.Name)
	}
	return nil
}

func validateChartAPIVersion(cf *chart.Metadata) error {
	if cf.APIVersion == "" {
		return errors.New("apiVersion is required. The value must be \"v3\"")
	}

	if cf.APIVersion != chart.APIVersionV3 {
		return fmt.Errorf("apiVersion '%s' is not valid. The value must be \"v3\"", cf.APIVersion)
	}

	return nil
}

func validateChartVersion(cf *chart.Metadata) error {
	if cf.Version == "" {
		return errors.New("version is required")
	}

	version, err := semver.StrictNewVersion(cf.Version)
	if err != nil {
		return fmt.Errorf("version '%s' is not a valid SemVerV2", cf.Version)
	}

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Make every bracketed segment a plain non-negative integer
2. Ensure each '[' has a matching ']' before the next delimiter
3. Use dot notation for named sub-keys (a[0].name=x) instead of bracket keys

Example fix

// before
strvals.ParseLiteral("matrix[0][row]=1")
// after
strvals.ParseLiteral("matrix[0][0]=1")

var bracket = regexp.MustCompile(`\[([^\]]*)\]`)
func allIndexesNumeric(s string) bool {
    for _, m := range bracket.FindAllStringSubmatch(s, -1) {
        n, err := strconv.Atoi(m[1]); if err != nil || n < 0 { return false }
    }
    return true
}

if err := strvals.ParseLiteral(s); err != nil && strings.Contains(err.Error(), "error parsing index") {
    return fmt.Errorf("nested index in %q must be an integer: %w", s, err)
}

When it happens

Trigger: ParseLiteral("a[0][x]=1") — non-numeric nested index. ParseLiteral("a[0][]=1") — empty index Atoi("") fails. ParseLiteral("a[0][1.5]=1") — float index. Unterminated bracket: ParseLiteral("a[0][1=1") reads '1=1' until EOF and Atoi fails.

Common situations: Hand-written nested list paths; expecting associative keys inside lists; a missing ']' that shifts what the parser reads as the index.

Related errors

• should be a file, not a directory
• name is required
• Chart.yaml file is missing
• version is required
• each maintainer requires a name

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