microsoft/aspire · error · ArgumentException

Helm chart name ' ' is invalid. It must be 250 characters…

Error message

Helm chart name '{name}' is invalid. It must be 250 characters or fewer.

What it means

Aspire's Kubernetes hosting integration rejects Helm chart names longer than 250 characters. The name is written into Helm chart metadata, which enforces a maximum length, so WithChartName validates eagerly and throws ArgumentException instead of emitting an invalid chart.

Solutions

1. Shorten the chart name passed to WithChartName to 250 characters or fewer.
2. If the name is composed at runtime, truncate it before calling WithChartName.
3. Use a short, stable chart name and put longer descriptive info in the chart description field.

Example fix

// before
builder.AddKubernetesEnvironment("env")
    .WithChartName("my-very-long-team-department-product-environment-" + longSuffix);
// after
var chartName = $"my-chart-{environment}";
builder.AddKubernetesEnvironment("env")
    .WithChartName(chartName.Length <= 250 ? chartName : chartName[..250]);

if (chartName is null || chartName.Length > 250) throw new ArgumentException($"Chart name must be 250 chars or fewer, got {chartName?.Length}.");

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

When it happens

Trigger: Calling WithChartName on a Kubernetes resource with a string whose Length exceeds HelmChartNameMaxLength (250).

Common situations: Programmatically composed names (app+environment+suffix concatenation) in long CI/CD pipelines or deeply nested team/org naming conventions that accidentally exceed 250 chars.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Helm chart reference
• Helm value contains an unsupported character
• Helm value key ' ' is invalid. Use letters, digits, '.'…
• Cannot derive a Helm release name from resource name
• Chart version must be a string or a parameter resource…

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

Appendix: source

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

    // Matches Helm's own chart-version validation, which uses the lenient SemVer parser
    // (Masterminds/semver/v3 NewVersion) — see helm/helm pkg/chart/v2/metadata.go isValidSemver.
    // Helm accepts a leading "v" and partial versions (e.g. "v1", "1", "1.2"), coercing them
    // to a full semantic version. Leading zeros are not allowed.
    internal const SemVersionStyles ChartVersionStyles = SemVersionStyles.AllowV | SemVersionStyles.OptionalMinorPatch;

    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();

View on GitHub (pinned to 25830f84bd)