microsoft/aspire · error · InvalidOperationException

Helm release name ' ' is invalid. Use lowercase letters…

Error message

Helm release name '{releaseName}' is invalid. Use lowercase letters, numbers, and hyphens, start and end with an alphanumeric character, and stay within 53 characters. Set an explicit release name with .WithHelm(h => h.WithReleaseName("my-release")).

What it means

Aspire's Helm deployment engine derives a Helm release name from the Kubernetes environment resource and validates it against Helm's DNS-label rules before running 'helm upgrade --install'. Helm release names must be RFC-1123 DNS labels: lowercase alphanumeric characters and hyphens, starting and ending alphanumeric, at most 53 characters in this implementation. When the derived name violates those rules, the engine throws before invoking helm.

Solutions

1. Set an explicit valid release name with .WithHelm(h => h.WithReleaseName("my-release")) on the Kubernetes environment resource.
2. Rename the project/environment so the derived name is a valid DNS label (lowercase, numbers, hyphens, <=53 chars).
3. If only the length is the problem, shorten the explicit release name; the limit here is 53 characters (stricter than Kubernetes' 63).

Example fix

// before
var k8s = builder.AddKubernetesEnvironment("env");
// project name 'MyCompany.LongRunningApp.Host' derives an invalid release name

// after
var k8s = builder.AddKubernetesEnvironment("env")
    .WithHelm(helm =>
    {
        helm.WithReleaseName("my-long-running-app");
    });

using System.Text.RegularExpressions;
static partial class Guards
{
    [GeneratedRegex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")]
    public static partial partial Regex DnsLabel();

    public static bool IsValidHelmReleaseName(string name) =>
        name.Length <= 53 && Guards.DnsLabel().IsMatch(name);
}
// call before AddKubernetesEnvironment/deploy:
// if (!Guards.IsValidHelmReleaseName(derivedName)) use an explicit name via WithReleaseName().

static bool IsValidHelmReleaseName(string? name) =>
    !string.IsNullOrEmpty(name) && name.Length <= 53 &&
    System.Text.RegularExpressions.Regex.IsMatch(name, "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$");

When it happens

Trigger: ResolveReleaseNameAsync computes a release name (typically from the app host / environment project name) and calls ValidateHelmReleaseName; the error is thrown when that name exceeds HelmReleaseNameMaxLength (53) or fails the DnsLabelPattern regex - e.g. it contains uppercase letters, underscores, dots, spaces, or starts/ends with a hyphen.

Common situations: Project or environment names with underscores or uppercase (e.g. 'My_AppHost'), names auto-derived from long folder paths exceeding 53 characters, renaming a solution so the derived name starts with a digit-hyphen combo, or CI checkouts into directories with invalid characters.

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/Deployment/HelmDeploymentEngine.cs:95

            var resolvedNs = await nsAnnotation.Namespace.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
            if (!string.IsNullOrEmpty(resolvedNs))
            {
                ValidateKubernetesNamespace(resolvedNs);
                return resolvedNs;
            }
        }

        return "default";
    }

    private const int HelmReleaseNameMaxLength = 53;
    private const int KubernetesNamespaceMaxLength = 63;

    private static void ValidateHelmReleaseName(string releaseName)
    {
        if (releaseName.Length > HelmReleaseNameMaxLength || !DnsLabelPattern().IsMatch(releaseName))
        {
            throw new InvalidOperationException(
                $"Helm release name '{releaseName}' is invalid. Use lowercase letters, numbers, and hyphens, " +
                $"start and end with an alphanumeric character, and stay within {HelmReleaseNameMaxLength} characters. " +
                "Set an explicit release name with .WithHelm(h => h.WithReleaseName(\"my-release\")).");
        }
    }

    private static void ValidateKubernetesNamespace(string @namespace)
    {
        if (@namespace.Length > KubernetesNamespaceMaxLength || !DnsLabelPattern().IsMatch(@namespace))
        {
            throw new InvalidOperationException(
                $"Kubernetes namespace '{@namespace}' is invalid. Use lowercase letters, numbers, and hyphens, " +
                $"start and end with an alphanumeric character, and stay within {KubernetesNamespaceMaxLength} characters. " +
                "Set an explicit namespace with .WithHelm(h => h.WithNamespace(\"my-namespace\")).");
        }
    }

    [GeneratedRegex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")]

View on GitHub (pinned to 25830f84bd)