{"record":{"id":"b3d8d6abf0cc6873","repo":"microsoft/aspire","slug":"helm-release-name-releasename-is-invalid-use-lowercase","errorCode":null,"errorMessage":"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\")).","messagePattern":"Helm release name '(.+?)' 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\"\\)\\)\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Kubernetes/Deployment/HelmDeploymentEngine.cs","lineNumber":95,"sourceCode":"            var resolvedNs = await nsAnnotation.Namespace.GetValueAsync(context.CancellationToken).ConfigureAwait(false);\n            if (!string.IsNullOrEmpty(resolvedNs))\n            {\n                ValidateKubernetesNamespace(resolvedNs);\n                return resolvedNs;\n            }\n        }\n\n        return \"default\";\n    }\n\n    private const int HelmReleaseNameMaxLength = 53;\n    private const int KubernetesNamespaceMaxLength = 63;\n\n    private static void ValidateHelmReleaseName(string releaseName)\n    {\n        if (releaseName.Length > HelmReleaseNameMaxLength || !DnsLabelPattern().IsMatch(releaseName))\n        {\n            throw new InvalidOperationException(\n                $\"Helm release name '{releaseName}' is invalid. Use lowercase letters, numbers, and hyphens, \" +\n                $\"start and end with an alphanumeric character, and stay within {HelmReleaseNameMaxLength} characters. \" +\n                \"Set an explicit release name with .WithHelm(h => h.WithReleaseName(\\\"my-release\\\")).\");\n        }\n    }\n\n    private static void ValidateKubernetesNamespace(string @namespace)\n    {\n        if (@namespace.Length > KubernetesNamespaceMaxLength || !DnsLabelPattern().IsMatch(@namespace))\n        {\n            throw new InvalidOperationException(\n                $\"Kubernetes namespace '{@namespace}' is invalid. Use lowercase letters, numbers, and hyphens, \" +\n                $\"start and end with an alphanumeric character, and stay within {KubernetesNamespaceMaxLength} characters. \" +\n                \"Set an explicit namespace with .WithHelm(h => h.WithNamespace(\\\"my-namespace\\\")).\");\n        }\n    }\n\n    [GeneratedRegex(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\")]","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Kubernetes/Deployment/HelmDeploymentEngine.cs#L77-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set an explicit valid release name with .WithHelm(h => h.WithReleaseName(\"my-release\")) on the Kubernetes environment resource.","Rename the project/environment so the derived name is a valid DNS label (lowercase, numbers, hyphens, <=53 chars).","If only the length is the problem, shorten the explicit release name; the limit here is 53 characters (stricter than Kubernetes' 63)."],"exampleFix":"// before\nvar k8s = builder.AddKubernetesEnvironment(\"env\");\n// project name 'MyCompany.LongRunningApp.Host' derives an invalid release name\n\n// after\nvar k8s = builder.AddKubernetesEnvironment(\"env\")\n    .WithHelm(helm =>\n    {\n        helm.WithReleaseName(\"my-long-running-app\");\n    });","handlingStrategy":"validation","validationCode":"using System.Text.RegularExpressions;\nstatic partial class Guards\n{\n    [GeneratedRegex(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\")]\n    public static partial partial Regex DnsLabel();\n\n    public static bool IsValidHelmReleaseName(string name) =>\n        name.Length <= 53 && Guards.DnsLabel().IsMatch(name);\n}\n// call before AddKubernetesEnvironment/deploy:\n// if (!Guards.IsValidHelmReleaseName(derivedName)) use an explicit name via WithReleaseName().","typeGuard":"static bool IsValidHelmReleaseName(string? name) =>\n    !string.IsNullOrEmpty(name) && name.Length <= 53 &&\n    System.Text.RegularExpressions.Regex.IsMatch(name, \"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\");","tryCatchPattern":null,"preventionTips":["Always set an explicit release name with WithHelm(h => h.WithReleaseName(...)) instead of relying on derived project names.","Keep a single helper that sanitizes any name (lowercase, replace '_'/'.' with '-', trim hyphens, cap at 53) before deployment.","Beware CI checkout directory names - derived names may inherit invalid characters or excessive length."],"tags":["kubernetes","helm","validation","naming"],"backgroundTag":"invalid-identifier-format","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}