microsoft/aspire · error · ArgumentException

Helm chart reference

Error message

Helm chart reference '{chartReference}' is invalid. Use OCI/HTTP URLs, repo/chart names, or local paths containing only letters, digits, '.', '-', '_', '/', ':', '@', '+', '~'.

What it means

Aspire's Kubernetes hosting API validates Helm chart references passed to AddHelmChart before invoking Helm. The value is checked against a ChartReferencePattern regex that permits only OCI/HTTP(S) URLs, repo/chart names, or local paths composed of letters, digits, and the characters . - _ / : @ + ~. Anything containing spaces, quotes, shell metacharacters, or other disallowed characters is rejected with this ArgumentException.

Solutions

1. Remove any characters not in the allowed set (letters, digits, '.', '-', '_', '/', ':', '@', '+', '~') from the chart reference.
2. Specify the chart version via the dedicated version parameter of AddHelmChart instead of embedding it in the reference.
3. For local charts, pass a path using forward slashes and without spaces; quote-free relative or absolute paths only.
4. For OCI charts use the oci://registry/repo/chart form; for HTTP use a full https:// URL with no query string.
5. For complex charts (set files, multiple values), use the WithHelmValue / --values-file style APIs rather than encoding options in the reference.

Example fix

// before
builder.AddHelmChart("web", "bitnami/nginx?version=15.0");
// after
builder.AddHelmChart("web", "bitnami/nginx", version: "15.0");

var allowed = new System.Text.RegularExpressions.Regex("^[a-zA-Z0-9./:_@+~-]+$");
if (string.IsNullOrEmpty(chartReference) || !allowed.IsMatch(chartReference))
    throw new ArgumentException($"Invalid chart reference: {chartReference}");

try { builder.AddHelmChart(name, chartReference); }
catch (ArgumentException ex) when (ex.Message.Contains("chart reference"))
{ logger.LogError(ex, "Chart reference '{Ref}' contains unsupported characters", chartReference); }

When it happens

Trigger: Calling AddHelmChart (or WithChartReference overloads that route to ValidateChartReference) with a chart reference containing characters outside the allowed set, e.g. 'bitnami/nginx (stable)', a URL with query string '?version=1.0', a quoted name, a path with spaces, or a reference using characters like '%', '#', ',', or '='.

Common situations: Copy-pasting a Helm command line argument (which may include flags or quotes) into the chart reference string; embedding an OCI reference with digest syntax containing characters outside the whitelist; using a Windows path with backslashes; appending version or values inline in the reference instead of using dedicated API parameters.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Helm chart name ' ' is invalid. It must be 250 characters…
• Helm value contains an unsupported character
• Helm value key ' ' is invalid. Use letters, digits, '.'…
• Cannot derive a Helm release name from resource name
• Chart version must be a string or a parameter resource…

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

Appendix: source

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

        => $"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();

    // Disallowed in helm --set keys: anything that would break the key=value tokenization or
    // interact with helm's escape syntax. Allow alphanumerics plus dot, dash, underscore,
    // and brackets (for indexed/array paths like "args[0]").
    [GeneratedRegex(@"^[A-Za-z0-9_.\-\[\]]+$")]
    private static partial Regex HelmSetKeyPattern();

    private static void ValidateChartReference(string chartReference, string paramName)
    {
        if (!ChartReferencePattern().IsMatch(chartReference))
        {
            throw new ArgumentException(
                $"Helm chart reference '{chartReference}' is invalid. Use OCI/HTTP URLs, repo/chart names, or local paths containing only letters, digits, '.', '-', '_', '/', ':', '@', '+', '~'.",
                paramName);
        }
    }

    private static void ValidateHelmSetKey(string key, string paramName)
    {
        if (!HelmSetKeyPattern().IsMatch(key))
        {
            throw new ArgumentException(
                $"Helm value key '{key}' is invalid. Use letters, digits, '.', '-', '_', or brackets for indexed paths.",
                paramName);
        }
    }

    private static void ValidateHelmSetValue(string value, string paramName)
    {
        // Reject control characters (newlines, tabs) and double-quotes that would break the

View on GitHub (pinned to 25830f84bd)