microsoft/aspire · error · InvalidOperationException

Cannot derive a Helm release name from resource name

Error message

Cannot derive a Helm release name from resource name '{chart.Name}'. Set an explicit release name via WithReleaseName(...). {ex.Message}

What it means

When no explicit release name is set, the chart's resource name is used as the Helm release name and validated with HelmChartOptions.ValidateReleaseName. If the resource name is not a valid Helm release name (DNS-1123 label rules), the caught ArgumentException is wrapped in this InvalidOperationException advising WithReleaseName.

Solutions

1. Set an explicit valid release name via WithReleaseName(...)
2. Rename the resource to a DNS-1123-compliant lowercase name (lowercase alphanumerics and '-', max 53 chars)
3. Read ex.Message (embedded) for the specific validation rule violated

Example fix

// before
env.AddHelmChart("My_Org_Chart_With_A_Very_Long_Descriptive_Name", ...);
// after
env.AddHelmChart("My_Org_Chart_With_A_Very_Long_Descriptive_Name", ...)
   .WithReleaseName("my-org-chart");

// RFC 1123 label check (Helm release names are max 53 chars)
bool IsValidReleaseName(string name) =>
    name.Length <= 53 && Regex.IsMatch(name, "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$");

try { env.AddHelmChart(chartName, ...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Cannot derive a Helm release name"))
{ logger.LogError(ex, "Set WithReleaseName(...) for resource '{Name}'.", chartName); }

When it happens

Trigger: Calling AddHelmChart with a resource name that violates Helm release-name rules (uppercase letters, underscores, too long >53 chars, starts/ends with '-', contains '.') while not calling WithReleaseName.

Common situations: C# identifiers like 'MyChart_1' or long descriptive resource names that exceed the 53-character Helm release limit.

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

• Helm chart name ' ' is invalid. Use alphanumeric…
• 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/7be0093514ee8574. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesHelmChartExtensions.cs:483

    private static (string ReleaseName, string Namespace) ResolveReleaseAndNamespace(KubernetesHelmChartResource chart)
    {
        var releaseName = chart.ReleaseName ?? chart.Name;
        var @namespace = chart.Namespace ?? chart.Name;

        // The fallback to chart.Name can produce a value that isn't a valid Helm release name or
        // Kubernetes namespace (uppercase, too long, etc.) — Aspire resource names allow more than
        // DNS labels do. Validate here so the caller gets a clear ArgumentException pointing at
        // WithReleaseName / WithNamespace instead of an opaque helm CLI failure.
        if (chart.ReleaseName is null)
        {
            try
            {
                HelmChartOptions.ValidateReleaseName(releaseName, nameof(chart.ReleaseName));
            }
            catch (ArgumentException ex)
            {
                throw new InvalidOperationException(
                    $"Cannot derive a Helm release name from resource name '{chart.Name}'. " +
                    $"Set an explicit release name via WithReleaseName(...). {ex.Message}",
                    ex);
            }
        }

        if (chart.Namespace is null)
        {
            try
            {
                HelmChartOptions.ValidateNamespace(@namespace, nameof(chart.Namespace));
            }
            catch (ArgumentException ex)
            {
                throw new InvalidOperationException(
                    $"Cannot derive a Kubernetes namespace from resource name '{chart.Name}'. " +
                    $"Set an explicit namespace via WithNamespace(...). {ex.Message}",
                    ex);

View on GitHub (pinned to 25830f84bd)