microsoft/aspire · error · ArgumentException

Helm chart name ' ' is invalid. Use alphanumeric…

Error message

Helm chart name '{name}' is invalid. Use alphanumeric characters, '-', '_', or '.'.

What it means

Helm chart names must consist only of lowercase alphanumeric characters, '-', '_', and '.'. WithChartName checks the name against HelmChartNamePattern and throws ArgumentException when it contains disallowed characters such as spaces, uppercase letters, slashes, or colons.

Solutions

1. Change the chart name to use only lowercase letters, digits, '-', '_', and '.'.
2. Sanitize the name (replace invalid characters with '-') before calling WithChartName.
3. Use a slug/kebab-case version of the project name as the chart name.

Example fix

// before
.WithChartName("My App Chart");
// after
.WithChartName("my-app-chart");

var valid = System.Text.RegularExpressions.Regex.IsMatch(chartName, "^[a-zA-Z0-9._-]+$");

try { builder.WithChartName(name); } catch (ArgumentException ex) when (ex.Message.Contains("alphanumeric")) { /* sanitize and retry */ }

When it happens

Trigger: Calling WithChartName with a name containing characters outside [alphanumeric, '-', '_', '.'], e.g. 'My Chart', 'my/chart', or a name starting with a special character.

Common situations: Passing a display name, resource name with a namespace prefix ('ns/mychart'), or Windows path fragment as the chart name; uppercase names copied from project names.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Cannot derive a Helm release name from resource name
• Helm release name ' ' is invalid. Use lowercase letters…
• Kubernetes namespace
• Cannot derive a Kubernetes namespace from resource name
• cert-manager resource name

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/97e5467b6b49e888. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/HelmChartOptions.cs:317

    internal static void ValidateChartVersion(string version, string paramName)
    {
        if (!SemVersion.TryParse(version, ChartVersionStyles, out _))
        {
            throw new ArgumentException($"Helm chart version '{version}' is invalid. Helm accepts versions such as '1.2.3', '1.2.3-beta.1+ef365', '1', '1.2', or 'v1.2.3'.", paramName);
        }
    }

    internal static void ValidateChartName(string name, string paramName)
    {
        if (name.Length > HelmChartNameMaxLength)
        {
            throw new ArgumentException($"Helm chart name '{name}' is invalid. It must be {HelmChartNameMaxLength} characters or fewer.", paramName);
        }

        if (!HelmChartNamePattern().IsMatch(name))
        {
            throw new ArgumentException($"Helm chart name '{name}' is invalid. Use alphanumeric characters, '-', '_', or '.'.", paramName);
        }
    }

    internal static void ValidateChartDescription(string description, string paramName)
    {
        if (description.Length > HelmChartDescriptionMaxLength)
        {
            throw new ArgumentException($"Helm chart description is invalid. It must be {HelmChartDescriptionMaxLength} characters or fewer.", paramName);
        }
    }

    [GeneratedRegex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")]
    private static partial Regex DnsLabelPattern();

    [GeneratedRegex("^[a-zA-Z0-9._-]+$")]
    private static partial Regex HelmChartNamePattern();
}

View on GitHub (pinned to 25830f84bd)