microsoft/aspire · error · ArgumentException

Helm value key ' ' is invalid. Use letters, digits, '.'…

Error message

Helm value key '{key}' is invalid. Use letters, digits, '.', '-', '_', or brackets for indexed paths.

What it means

Aspire validates every key passed to WithHelmValue against a HelmSetKeyPattern that allows letters, digits, '.', '-', '_' plus bracket notation for indexed array paths (e.g. ingress.hosts[0].host). This mirrors Helm --set key semantics. Keys with other characters (spaces, '=', quotes, unbalanced brackets) are rejected because they would produce invalid or ambiguous Helm --set arguments.

Solutions

Use only letters, digits, '.', '-', '_' and balanced bracket indexes (e.g. hosts[0]) in the key.
If you pasted a 'key=value' pair, split it: pass only the key part as the key argument and the value part as the value argument.
For keys with unusual names that cannot fit the pattern, use a values file supplied to the chart instead of WithHelmValue.
Check bracket syntax: every '[' must be matched by ']' and contain a valid index.

Example fix

// before
.WithHelmValue("ingress.hosts[0.host", "example.com");
// after
.WithHelmValue("ingress.hosts[0].host", "example.com");

Defensive patterns

Strategy: validation

Validate before calling

var allowed = new System.Text.RegularExpressions.Regex("^[a-zA-Z0-9._-]+(\[[0-9]+\])?([a-zA-Z0-9._-]*(\[[0-9]+\])?)*$");
// simpler guard: restrict to pattern-safe chars and balanced [n] segments
if (!System.Text.RegularExpressions.Regex.IsMatch(key, "^[a-zA-Z0-9._-]+(\[[0-9]+\])?([a-zA-Z0-9._-]+(\[[0-9]+\])?)*$"))
    throw new ArgumentException($"Invalid Helm set key: {key}");

Try / catch

try { resource.WithHelmValue(key, value); }
catch (ArgumentException ex) when (ex.Message.Contains("Helm value key"))
{ logger.LogError(ex, "Invalid Helm set key '{Key}'", key); }

Prevention

Model keys as dotted paths with bracket indexes only, e.g. a.b[0].c.
Never paste 'key=value' pairs into the key argument.
Use values files for keys that don't fit the allowed character set.

When it happens

Trigger: Calling WithHelmValue with a key such as 'service port', 'a=b', 'ingress.hosts[0', 'hosts[]', or any string containing characters outside the allowed pattern.

Common situations: Misremembering Helm --set syntax (using '=' inside the key instead of as the separator in raw Helm CLI usage); typos in indexed paths like missing the index number in brackets; accidentally pasting a full 'key=value' pair into the key argument.

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

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

Appendix: source

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

    // 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
        // surrounding quoted argument we hand to the OS process. Helm itself supports richer
        // value syntax via --set-file / --set-string, which users can wire up later if needed.
        foreach (var c in value)
        {
            if (c == '"' || c == '\\' || char.IsControl(c))
            {
                throw new ArgumentException(
                    $"Helm value contains an unsupported character (0x{(int)c:X2}). Avoid quotes, backslashes, and control characters; use --values files for complex values.",
                    paramName);
            }

View on GitHub (pinned to 25830f84bd)