microsoft/aspire · error · ArgumentException

Helm value contains an unsupported character

Error message

Helm value contains an unsupported character (0x{c:X2}). Avoid quotes, backslashes, and control characters; use --values files for complex values.

What it means

Aspire validates Helm values passed to WithHelmValue to ensure the resulting Helm --set command-line argument is safe. Values containing double quotes, backslashes, or any control character are rejected because they would break quoting/escaping of the OS process argument. Complex values needing quotes should be provided via a values file (--values / --set-file), as the comment in the source notes.

Solutions

Remove or replace quotes, backslashes, and control characters (trim whitespace/newlines from values read from files).
Use forward slashes for paths inside the value.
For complex values (JSON, YAML, multi-line, quoted), write them to a values file and supply it through the chart's values-file API instead of WithHelmValue.
Use Helm's --set-string / --set-file semantics via the appropriate Aspire API if the value must be treated literally.

Example fix

// before
.WithHelmValue("config", "{\"a\": 1}\n");
// after
.WithHelmValue("config", "{a: 1}"); // or supply a values file for complex payloads

Defensive patterns

Strategy: validation

Validate before calling

if (value.Any(c => c == '"' || c == '\\' || char.IsControl(c)))
    throw new ArgumentException("Helm value contains quotes, backslashes, or control characters");

Try / catch

try { resource.WithHelmValue(key, value); }
catch (ArgumentException ex) when (ex.Message.Contains("unsupported character"))
{ logger.LogError(ex, "Value for '{Key}' contains quotes/backslashes/control chars; use a values file", key); }

Prevention

Trim values read from files or environment variables to remove trailing newlines/tabs.
Use forward slashes for any path-like values.
Move complex or quoted values into a values file instead of WithHelmValue.

When it happens

Trigger: Calling WithHelmValue with a value containing a double quote, a backslash (e.g. a Windows path or regex), or a control character such as a newline, tab, or carriage return embedded in the string.

Common situations: Passing multi-line YAML/JSON or a formatted string as a single --set value; passing Windows file paths with backslashes; strings read from files or user input that include trailing newlines or tabs; attempting to embed quoted shell fragments in the value.

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/831918e369255a44. Report an issue: GitHub.

Appendix: source

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

    {
        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);
            }
        }
    }

    // Wraps an already-validated argument fragment in double quotes for safe interpolation
    // into the helm arguments string. Callers must validate that the value contains no
    // embedded quotes, backslashes, or control characters first.
    private static string QuoteArg(string value) => $"\"{value}\"";
}

View on GitHub (pinned to 25830f84bd)