microsoft/aspire · error · InvalidOperationException

Cannot derive a Kubernetes namespace from resource name

Error message

Cannot derive a Kubernetes namespace from resource name '{chart.Name}'. Set an explicit namespace via WithNamespace(...). {ex.Message}

What it means

When no explicit namespace is set, the chart's resource name is used as the Kubernetes namespace and validated with HelmChartOptions.ValidateNamespace. If it fails namespace rules (RFC 1123 label: lowercase alphanumerics and '-', max 63 chars), the ArgumentException is wrapped in this InvalidOperationException advising WithNamespace.

Solutions

Set an explicit namespace via WithNamespace(...) with an RFC 1123-compliant label
Rename the resource to lowercase alphanumerics/hyphens within 63 characters
Read the embedded ex.Message for the exact rule violated

Example fix

// before
env.AddHelmChart("MyChart_v2", ...); // name not a valid namespace
// after
env.AddHelmChart("MyChart_v2", ...)
   .WithNamespace("mychart");

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Call WithNamespace explicitly instead of relying on the resource name
Use lowercase alphanumeric/hyphen names of 63 chars or fewer
Avoid dots, underscores, and uppercase letters in resource names used as namespaces

When it happens

Trigger: Calling AddHelmChart with a resource name that is not a valid Kubernetes namespace (uppercase, underscores, dots, or over 63 characters) without calling WithNamespace.

Common situations: CamelCase or underscored C# resource names used directly as namespaces; resource names containing dots.

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

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

Appendix: source

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

            }
            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);
            }
        }

        return (releaseName, @namespace);
    }

    private static string GetStateSectionName(KubernetesEnvironmentResource environment, KubernetesHelmChartResource chart)
        => $"HelmChart:{environment.Name}:{chart.Name}";

    // Allowlist for Helm chart references. Covers OCI URLs (oci://host/path), HTTP/HTTPS URLs,
    // local paths, plain chart names ("repo/chart"), and packaged chart filenames. Rejects anything
    // that could break helm argument tokenization (whitespace, quotes, control chars).
    [GeneratedRegex(@"^[A-Za-z0-9_./:@+~\-]+$")]
    private static partial Regex ChartReferencePattern();

View on GitHub (pinned to 25830f84bd)