helm/helm · error

release name %q: %w

Error message

release name %q: %w

What it means

availableName() wraps chartutil.ValidateReleaseName failures, prefixing the offending name. ValidateReleaseName rejects empty names and names that are longer than 53 characters or do not fully match the DNS-1123-style pattern [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*. Unlike the storage-history check, this error is purely syntactic, so it fires even in dry runs.

Source

Thrown at pkg/action/install.go:612

		return rel, fmt.Errorf("release %s failed, and has been uninstalled due to rollback-on-failure being set: %w", i.ReleaseName, err)
	}
	i.recordRelease(rel) // Ignore the error, since we have another error to deal with.
	return rel, err
}

// availableName tests whether a name is available
//
// Roughly, this will return an error if name is
//
//   - empty
//   - too long
//   - already in use, and not deleted
//   - used by a deleted release, and i.Replace is false
func (i *Install) availableName() error {
	start := i.ReleaseName

	if err := chartutil.ValidateReleaseName(start); err != nil {
		return fmt.Errorf("release name %q: %w", start, err)
	}
	// On dry run, bail here
	if isDryRun(i.DryRunStrategy) {
		return nil
	}

	h, err := i.cfg.Releases.History(start)
	if err != nil || len(h) < 1 {
		return nil
	}

	hl, err := releaseListToV1List(h)
	if err != nil {
		return err
	}

	releaseutil.Reverse(hl, releaseutil.SortByRevision)
	rel := hl[0]

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Set a valid name: lowercase alphanumeric plus '-' and '.', no leading/trailing separators, max 53 characters
2. Sanitize generated names: lowercase and replace invalid chars (e.g. tr 'A-Z_' 'a-z-') before passing them
3. If templating names, keep the template output short and lowercased
4. Empty name in SDK usage: either set ReleaseName, GenerateName, or NameTemplate before Run

Example fix

# before
helm install "MyFeature_Branch" ./chart   # release name "MyFeature_Branch": ...

# after
helm install "myfeature-branch" ./chart

import "helm.sh/helm/v4/pkg/chart/v2/util"

func safeReleaseName(raw string) (string, error) {
    name := strings.ToLower(raw)
    name = strings.ReplaceAll(name, "_", "-")
    name = strings.Trim(name, "-.")
    if len(name) > 53 {
        name = name[:53]
    }
    if err := util.ValidateReleaseName(name); err != nil {
        return "", err
    }
    return name, nil
}

if _, err := inst.RunWithContext(ctx, chrt, vals); err != nil {
    if strings.Contains(err.Error(), "release name \"") {
        // sanitize the name per ValidateReleaseName rules and retry
    }
    return err
}

When it happens

Trigger: i.ReleaseName (or generated name from --name-template) is empty, >53 chars, or contains uppercase letters, underscores, spaces, or other invalid characters when ValidateReleaseName runs.

Common situations: Programmatic installs leaving the name empty; CI pipelines composing names from branch names (My_Feature); --name-template producing long or uppercased output; Helmfile/values-driven pipelines passing product display names.

Related errors

• release name check failed: %w
• must either provide a name or specify --generate-name
• chart name %q is invalid
• chart name must be between 1 and %d characters
• chart name must match the regular expression %q

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