microsoft/aspire · error · ArgumentException

Kubernetes namespace

Error message

Kubernetes namespace '{kubernetesNamespace}' is invalid. Must match RFC 1123: lowercase alphanumeric characters or hyphens, start and end with an alphanumeric character, and be at most {KubernetesNamespaceMaxLength} characters.

What it means

WithNamespace validates the Kubernetes namespace against RFC 1123 DNS label rules: lowercase alphanumeric and hyphens, starting/ending with an alphanumeric, and at most KubernetesNamespaceMaxLength (63) characters. Invalid namespaces would be rejected by Kubernetes at apply time, so the extension rejects them at configuration time with a clear ArgumentException.

Solutions

1. Lowercase the value and replace underscores with hyphens
2. Trim leading/trailing hyphens and non-alphanumeric characters
3. Shorten the value to at most 63 characters
4. Pre-generate a compliant name, e.g. app name converted with a slugify helper

Example fix

// before
.WithNamespace("MyApp_Prod")
// after
.WithNamespace("myapp-prod")

var valid = ns.Length <= 63 && System.Text.RegularExpressions.Regex.IsMatch(ns, "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"); if (!valid) throw new ArgumentException($"Namespace '{ns}' must be RFC 1123 compliant.");

bool IsValidK8sNamespace(string? ns) => ns is not null && ns.Length <= 63 && System.Text.RegularExpressions.Regex.IsMatch(ns, "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$");

try { env.WithNamespace(ns); } catch (ArgumentException ex) when (ex.ParamName == nameof(ns)) { logger.LogError(ex, "Invalid Kubernetes namespace"); throw; }

When it happens

Trigger: Calling radiusEnvironment.WithNamespace(...) with an uppercase name ('Default'), underscores ('my_ns'), a leading/trailing hyphen, a slash, or a string longer than 63 characters.

Common situations: Reusing an app/environment name with mixed case as a namespace; Windows-style identifiers with underscores; copy-pasting fully-qualified resource names into the namespace argument.

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

• ASPIRERADIUS046
• ASPIRERADIUS055
• ASPIRERADIUS061
• ASPIRERADIUS067
• A ConfigureRadiusInfrastructure callback left container

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

Appendix: source

Thrown at src/Aspire.Hosting.Radius/RadiusExtensions.cs:73

    /// <summary>
    /// Sets the Kubernetes namespace for the Radius environment.
    /// </summary>
    /// <param name="builder">The Radius environment resource builder.</param>
    /// <param name="kubernetesNamespace">A valid RFC 1123 namespace name.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{RadiusEnvironmentResource}"/>.</returns>
    /// <exception cref="ArgumentException">Thrown when the namespace is not a valid RFC 1123 label.</exception>
    [AspireExport]
    public static IResourceBuilder<RadiusEnvironmentResource> WithNamespace(
        this IResourceBuilder<RadiusEnvironmentResource> builder,
        string kubernetesNamespace)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(kubernetesNamespace);

        if (kubernetesNamespace.Length > KubernetesNamespaceMaxLength || !DnsLabelPattern().IsMatch(kubernetesNamespace))
        {
            throw new ArgumentException(
                $"Kubernetes namespace '{kubernetesNamespace}' is invalid. " +
                "Must match RFC 1123: lowercase alphanumeric characters or hyphens, " +
                $"start and end with an alphanumeric character, and be at most {KubernetesNamespaceMaxLength} characters.",
                nameof(kubernetesNamespace));
        }

        builder.Resource.Namespace = kubernetesNamespace;
        return builder;
    }

    /// <summary>
    /// Registers a callback that can customize the generated Radius infrastructure before Bicep is emitted.
    /// </summary>
    /// <param name="builder">The Radius environment resource builder.</param>
    /// <param name="configure">The callback that mutates the generated infrastructure options.</param>
    /// <returns>The same <see cref="IResourceBuilder{RadiusEnvironmentResource}"/> for chaining.</returns>
    [Experimental("ASPIRERADIUS004", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    [AspireExportIgnore(Reason = "RadiusInfrastructureOptions customization callbacks are not ATS-compatible.")]

View on GitHub (pinned to 25830f84bd)