helm/helm · error

chart name %q is invalid

Error message

chart name %q is invalid

What it means

Lint rule validating the metadata name: filepath.Base(cf.Name) must equal cf.Name, i.e. the chart name must be a single path element with no separators and no '..' tricks. 'foo/bar' fails because Base is 'bar'. Reported at ErrorSev.

Source

Thrown at pkg/chart/v2/lint/rules/chartfile.go:122

		return fmt.Errorf("unable to parse YAML\n\t%w", chartFileError)
	}
	return nil
}

func validateChartYamlStrictFormat(chartFileError error) error {
	if chartFileError != nil {
		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 either \"v1\" or \"v2\"")
	}

	if cf.APIVersion != chart.APIVersionV1 && cf.APIVersion != chart.APIVersionV2 {
		return fmt.Errorf("apiVersion '%s' is not valid. The value must be either \"v1\" or \"v2\"", cf.APIVersion)
	}

	return nil
}

func validateChartVersion(cf *chart.Metadata) error {
	if cf.Version == "" {

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Use a flat name: `name: mychart`.
2. Put organization/repo scoping in the repository or OCI reference (oci://registry/myorg/mychart), not in metadata.name.
3. Ensure the directory name matches the chart name as Helm convention expects.

Example fix

# before
apiVersion: v2
name: my-org/mychart   # -> chart name "my-org/mychart" is invalid

# after
apiVersion: v2
name: mychart          # scope lives in the repo/OCI path, not the name

// Enforce a flat chart name before publish
if filepath.Base(md.Name) != md.Name || md.Name == "" {
	return fmt.Errorf("chart name %q must be a single path element", md.Name)
}

When it happens

Trigger: Chart.yaml with `name: my-org/mychart`, `name: ./mychart`, `name: charts/backend`, or a name containing an OS path separator. Also note the empty-name case has its own 'name is required' error before this check.

Common situations: Wanting a 'grouped' chart name resembling an OCI repository path; scaffolding scripts injecting paths; porting charts from ecosystems where scoped names are allowed (npm style).

Related errors

• should be a file, not a directory
• name is required
• apiVersion is required. The value must be either "v1" or "v2
• version is required
• a maintainer entry is empty

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