microsoft/aspire · error · NotSupportedException

Command line args must be strings

Error message

Command line args must be strings

What it means

Thrown by ProcessArgumentsAsync in KubernetesResource when an argument reference resolves to a non-string value. During publish, all command-line arguments must be renderable as Helm string values, so any argument whose processed value is not a string is rejected with NotSupportedException.

Solutions

1. Convert the argument to a string before passing it (e.g. value.ToString() or string interpolation)
2. Use a ReferenceExpression with string formatting so the result is a string
3. Implement IValueProvider such that it returns string values
4. Catch and log which argument produced the non-string value by inspecting context.Args

Example fix

// before
container.WithArgs(42);
// after
container.WithArgs(42.ToString());

static string AsString(object? v) => v is string s ? s : Convert.ToString(v, CultureInfo.InvariantCulture) ?? throw new InvalidOperationException("Arg must be string");

try { PublishAsync(...); }
catch (NotSupportedException ex) when (ex.Message == "Command line args must be strings") { /* stringify the offending arg */ }

When it happens

Trigger: Using WithArgs with an expression/value provider that evaluates to a non-string (e.g. an int, bool, or custom object) instead of a string or a ReferenceExpression producing strings.

Common situations: Passing numeric literals or enums directly via WithArgs; a custom IValueProvider returning non-string values; version changes where an argument source stopped stringifying its output.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Expected Int32OrStringV1 but got
• Expected KubernetesManifestResource but got
• Invalid type for option
• Model must be a FoundryModel or a string model name.
• Resource ' ' maps both and to Helm values path ' . . '…

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesResource.cs:383

        if (resource.TryGetAnnotationsOfType<CommandLineArgsCallbackAnnotation>(out var commandLineArgsCallbackAnnotations))
        {
            var context = new CommandLineArgsCallbackContext([], resource, cancellationToken: cancellationToken)
            {
                ExecutionContext = executionContext
            };

            foreach (var c in commandLineArgsCallbackAnnotations)
            {
                await c.Callback(context).ConfigureAwait(false);
            }

            foreach (var arg in context.Args)
            {
                var value = await ProcessValueAsync(environmentContext, executionContext, arg).ConfigureAwait(false);

                if (value is not string str)
                {
                    throw new NotSupportedException("Command line args must be strings");
                }

                Commands.Add(new(str));
            }
        }
    }

    private async Task ProcessEnvironmentAsync(KubernetesEnvironmentContext environmentContext, DistributedApplicationExecutionContext executionContext, CancellationToken cancellationToken)
    {
        if (resource.TryGetAnnotationsOfType<EnvironmentCallbackAnnotation>(out var environmentCallbacks))
        {
            var context = new EnvironmentCallbackContext(executionContext, resource, cancellationToken: cancellationToken);

            foreach (var c in environmentCallbacks)
            {
                await c.Callback(context).ConfigureAwait(false);
            }

View on GitHub (pinned to 25830f84bd)