microsoft/aspire · error · ArgumentException

Chart version must be a string or a parameter resource…

Error message

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

What it means

WithChartVersion(object) accepts either a string chart version or an IResourceBuilder<ParameterResource>; any other type throws ArgumentException. Like the other HelmChartOptions overloads, a type-switch narrows to the strongly-typed implementations and rejects everything else.

Solutions

1. Pass a version string: .WithChartVersion("1.2.3").
2. Pass an IResourceBuilder<ParameterResource> created with builder.AddParameter(...).
3. Convert non-string version representations to a SemVer string before calling.

Example fix

// before
helmOptions.WithChartVersion(new Version(1, 2, 3));
// after
helmOptions.WithChartVersion("1.2.3");
// or
var versionParam = builder.AddParameter("chartVersion");
helmOptions.WithChartVersion(versionParam);

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

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

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

When it happens

Trigger: Calling .WithChartVersion() with a value whose runtime type is neither string nor IResourceBuilder<ParameterResource> (e.g. a Version object, a double like 1.2, or a wrapper).

Common situations: Passing a System.Version or numeric version instead of a SemVer string; passing a parameter value instead of a parameter resource builder; value typed as object from configuration.

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

• Helm chart name ' ' is invalid. It must be 250 characters…
• Helm chart reference
• Helm value contains an unsupported character
• Helm value key ' ' is invalid. Use letters, digits, '.'…
• Namespace must be a string or a parameter resource builder.

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

Appendix: source

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

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

    /// <summary>
    /// Sets the Helm chart version for deployment.
    /// </summary>
    [AspireExport(MethodName = "withChartVersion")]
    internal HelmChartOptions WithChartVersion([AspireUnion(typeof(string), typeof(IResourceBuilder<ParameterResource>))] object version)
    {
        ArgumentNullException.ThrowIfNull(version);

        return version switch
        {
            string versionValue => WithChartVersion(versionValue),
            IResourceBuilder<ParameterResource> versionParameter => WithChartVersion(versionParameter),
            _ => throw new ArgumentException("Chart version must be a string or a parameter resource builder.", nameof(version))
        };
    }

    /// <summary>
    /// Sets the Helm chart name written to the generated <c>Chart.yaml</c>.
    /// </summary>
    /// <param name="name">The chart name. Must match Helm's chart-name format (alphanumeric, <c>-</c>, <c>_</c>, or <c>.</c>).</param>
    /// <returns>This <see cref="HelmChartOptions"/> for chaining.</returns>
    [AspireExportIgnore(Reason = "Polyglot AppHosts use the union-based withChartName dispatcher export.")]
    public HelmChartOptions WithChartName(string name)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(name);
        ValidateChartName(name, nameof(name));

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

View on GitHub (pinned to 25830f84bd)