{"record":{"id":"1e41f0773ccc4be1","repo":"microsoft/aspire","slug":"kubernetes-namespace-namespace-is-invalid-use-lowercase","errorCode":null,"errorMessage":"Kubernetes namespace '{@namespace}' is invalid. Use lowercase letters, numbers, and hyphens, start and end with an alphanumeric character, and stay within 63 characters. Set an explicit namespace with .WithHelm(h => h.WithNamespace(\"my-namespace\")).","messagePattern":"Kubernetes namespace '(.+?)' is invalid\\. Use lowercase letters, numbers, and hyphens, start and end with an alphanumeric character, and stay within 63 characters\\. Set an explicit namespace with \\.WithHelm\\(h => h\\.WithNamespace\\(\"my-namespace\"\\)\\)\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Kubernetes/Deployment/HelmDeploymentEngine.cs","lineNumber":106,"sourceCode":"    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])?$\")]\n    private static partial Regex DnsLabelPattern();\n\n    /// <summary>\n    /// Creates the deployment pipeline steps for the Helm engine.\n    /// </summary>\n    internal static Task<IReadOnlyList<PipelineStep>> CreateStepsAsync(\n        KubernetesEnvironmentResource environment,\n        PipelineStepFactoryContext factoryContext)\n    {\n        var model = factoryContext.PipelineContext.Model;\n        var steps = new List<PipelineStep>();","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Kubernetes/Deployment/HelmDeploymentEngine.cs#L88-L124","documentation":"The Kubernetes namespace the engine resolved for the Helm deployment is validated against RFC-1123 DNS-label rules (lowercase alphanumerics and hyphens, start/end alphanumeric, max 63 characters). An invalid namespace would be rejected by the Kubernetes API anyway, so Aspire fails fast with an actionable message before invoking helm.","triggerScenarios":"ResolveNamespaceAsync resolves the namespace (from the Kubernetes environment resource configuration) and calls ValidateKubernetesNamespace; the error is thrown when the namespace exceeds KubernetesNamespaceMaxLength (63) or fails DnsLabelPattern - uppercase letters, underscores, dots, leading/trailing hyphen, or empty after derivation.","commonSituations":"Setting a namespace with an underscore or uppercase via .WithHelm(h => h.WithNamespace(...)), environment names derived from branch names containing '/' or '_' in CI, or copying a namespace from a context that allows dots.","solutions":["Set an explicit valid namespace with .WithHelm(h => h.WithNamespace(\"my-namespace\")) using only lowercase letters, numbers, and hyphens.","Fix the configured/derived namespace source (e.g. sanitize a CI branch name before using it as a namespace).","Keep the namespace at 63 characters or fewer (this is the standard Kubernetes namespace limit)."],"exampleFix":"// before\n.WithHelm(h => h.WithNamespace(\"My_Namespace\"))\n\n// after\n.WithHelm(h => h.WithNamespace(\"my-namespace\"))","handlingStrategy":"validation","validationCode":"static bool IsValidKubernetesNamespace(string? ns) =>\n    !string.IsNullOrEmpty(ns) && ns.Length <= 63 &&\n    System.Text.RegularExpressions.Regex.IsMatch(ns, \"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\");\n// validate before WithNamespace() / deploy.","typeGuard":"static bool IsValidKubernetesNamespace(string? ns) =>\n    !string.IsNullOrEmpty(ns) && ns.Length <= 63 &&\n    System.Text.RegularExpressions.Regex.IsMatch(ns, \"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\");","tryCatchPattern":null,"preventionTips":["Pass literal, known-valid namespaces via WithHelm(h => h.WithNamespace(\"my-namespace\")).","Sanitize dynamic sources (branch names, env names): lowercase, replace invalid chars with '-', trim leading/trailing hyphens, cap at 63.","Remember namespaces do not allow dots or underscores, unlike some other Kubernetes name kinds."],"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"}