microsoft/aspire · error · ArgumentException

Chart name must be a string or a parameter resource builder.

Error message

Chart name must be a string or a parameter resource builder.

What it means

This error is thrown by the WithChartName overload that accepts `object name` when the value is neither a string nor an IResourceBuilder<ParameterResource>. The Kubernetes publishing API requires the Helm chart name to be either a literal string or a parameter resource so it can be resolved at publish time; anything else is rejected. It is an ArgumentException naming the `name` parameter.

Solutions

1. Pass a plain string: builder.PublishAsKubernetesHelmChart(...).WithChartName("mychart")
2. Pass an IResourceBuilder<ParameterResource> obtained from builder.AddParameter("chart-name")
3. If the value comes in as object, cast or convert to string first (e.g. obj as string ?? throw) before calling WithChartName

Example fix

// before
object chartName = config["ChartName"];
.WithChartName(chartName) // throws
// after
string chartName = config["ChartName"]!;
.WithChartName(chartName)

public static bool IsValidChartNameArg(object? name) => name is string or IResourceBuilder<ParameterResource>;

var ok = name is string || name is IResourceBuilder<ParameterResource>;

try { chart.WithChartName(nameValue); }
catch (ArgumentException ex) when (ex.ParamName == "name") { /* fall back to a default chart name or fail fast with a clear message */ }

When it happens

Trigger: Calling WithChartName with a value whose compile-time type is object (or a dynamic value) that is not a string or IResourceBuilder<ParameterResource> — e.g. passing an int, a char, or a builder of the wrong resource type.

Common situations: Developers pass a variable typed as object (read from configuration or deserialized JSON) into WithChartName without casting to string; or they pass an IResourceBuilder of a non-Parameter resource type assuming it is accepted.

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

• Chart description must be a string or a parameter resource…
• Cannot derive a Helm release name from resource name
• Cannot derive a Kubernetes namespace from resource name
• Chart version must be a string or a parameter resource…
• Could not parse Helm version from 'helm version --short'…

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

Appendix: source

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

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

    /// <summary>
    /// Sets the Helm chart name written to the generated Chart.yaml.
    /// </summary>
    [AspireExport(MethodName = "withChartName")]
    internal HelmChartOptions WithChartName([AspireUnion(typeof(string), typeof(IResourceBuilder<ParameterResource>))] object name)
    {
        ArgumentNullException.ThrowIfNull(name);

        return name switch
        {
            string nameValue => WithChartName(nameValue),
            IResourceBuilder<ParameterResource> nameParameter => WithChartName(nameParameter),
            _ => throw new ArgumentException("Chart name must be a string or a parameter resource builder.", nameof(name))
        };
    }

    /// <summary>
    /// Sets the Helm chart description written to the generated <c>Chart.yaml</c>.
    /// </summary>
    /// <param name="description">The chart description.</param>
    /// <returns>This <see cref="HelmChartOptions"/> for chaining.</returns>
    [AspireExportIgnore(Reason = "Polyglot AppHosts use the union-based withChartDescription dispatcher export.")]
    public HelmChartOptions WithChartDescription(string description)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(description);
        ValidateChartDescription(description, nameof(description));

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

View on GitHub (pinned to 25830f84bd)