microsoft/aspire · error · ArgumentException

Namespace must be a string or a parameter resource builder.

Error message

Namespace must be a string or a parameter resource builder.

What it means

WithNamespace(object) accepts either a string namespace name or an IResourceBuilder<ParameterResource>; anything else is rejected with ArgumentException. The overload exists so callers can pass a static value or a parameter that resolves at publish time, and the switch exhaustively guards the accepted types.

Solutions

Pass a plain string: .WithNamespace("my-namespace").
Pass a parameter builder created via builder.AddParameter(...): .WithNamespace(paramBuilder).
Convert the value to a string before calling if it is a name-like object.

Example fix

// before
object ns = 42;
helmOptions.WithNamespace(ns);
// after
helmOptions.WithNamespace("my-namespace");
// or with a parameter
var nsParam = builder.AddParameter("namespace");
helmOptions.WithNamespace(nsParam);

Defensive patterns

Strategy: type-guard

Validate before calling

bool isValidNamespaceArg(object? value) => value is string or IResourceBuilder<ParameterResource>;

Type guard

static bool IsNamespaceArg(object? value) => value is string or IResourceBuilder<ParameterResource>;

Try / catch

try { options.WithNamespace(value); }
catch (ArgumentException ex) { logger.LogError(ex, "Namespace must be a string or IResourceBuilder<ParameterResource>"); }

Prevention

Pass literal strings or builder.AddParameter() results to WithNamespace.
Avoid storing namespace arguments in object/dynamic variables.
Check the XML docs on the overload to confirm accepted types before calling.

When it happens

Trigger: Calling .WithNamespace() with a value whose runtime type is neither string nor IResourceBuilder<ParameterResource> (e.g. an int, a resolvable object, or null-adjacent wrong type passed as object).

Common situations: Passing a variable typed as object/dynamic holding something unexpected; passing a parameter value instead of a parameter resource builder; passing a KubernetesNamespace-like wrapper instead of a string.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/HelmChartOptions.cs:78

        var expression = ReferenceExpression.Create($"{@namespace.Resource}");
        EnvironmentBuilder.WithAnnotation(new KubernetesNamespaceAnnotation(expression), ResourceAnnotationMutationBehavior.Replace);
        return this;
    }

    /// <summary>
    /// Sets the target Kubernetes namespace for deployment.
    /// </summary>
    [AspireExport(MethodName = "withNamespace")]
    internal HelmChartOptions WithNamespace([AspireUnion(typeof(string), typeof(IResourceBuilder<ParameterResource>))] object @namespace)
    {
        ArgumentNullException.ThrowIfNull(@namespace);

        return @namespace switch
        {
            string namespaceName => WithNamespace(namespaceName),
            IResourceBuilder<ParameterResource> namespaceParameter => WithNamespace(namespaceParameter),
            _ => throw new ArgumentException("Namespace must be a string or a parameter resource builder.", nameof(@namespace))
        };
    }

    /// <summary>
    /// Sets the Helm release name for deployment.
    /// </summary>
    /// <param name="releaseName">The release name.</param>
    /// <returns>This <see cref="HelmChartOptions"/> for chaining.</returns>
    [AspireExportIgnore(Reason = "Polyglot AppHosts use the union-based withReleaseName dispatcher export.")]
    public HelmChartOptions WithReleaseName(string releaseName)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(releaseName);
        ValidateReleaseName(releaseName, nameof(releaseName));

        var expression = ReferenceExpression.Create($"{releaseName}");
        EnvironmentBuilder.WithAnnotation(new HelmReleaseNameAnnotation(expression), ResourceAnnotationMutationBehavior.Replace);
        return this;
    }

View on GitHub (pinned to 25830f84bd)