microsoft/aspire · error · NotSupportedException

Command line args must be strings

Error message

Command line args must be strings

What it means

Type guard in AddEnvironmentVariablesAndCommandLineArgsAsync: while materializing the service's Args, one argument value resolved by ProcessValueAsync to a non-string object (e.g. an int, bool, or resource reference result). The compose file serializer only accepts string command-line tokens, so the resolved value's runtime type is rejected.

Solutions

1. Wrap the argument in an expression that converts it to string, e.g. "{arg.Value}" formatting, so ProcessValueAsync yields a string
2. Avoid passing raw numeric/boolean literal values directly in Args for compose targets
3. Check for unresolved resource references (connection strings, endpoints) being passed as args and project them to strings first

When it happens

Trigger: Thrown at src/Aspire.Hosting.Docker/DockerComposeServiceResource.cs:244 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at src/Aspire.Hosting.Docker/DockerComposeServiceResource.cs:244

        }

        if (env.Count > 0)
        {
            foreach (var variable in env)
            {
                composeService.AddEnvironmentalVariable(variable.Key, variable.Value);
            }
        }

        var args = new List<string>();

        foreach (var arg in Args)
        {
            var value = await this.ProcessValueAsync(arg).ConfigureAwait(false);

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

            args.Add(str);
        }

        if (args.Count > 0)
        {
            if (IsShellExec)
            {
                var sb = new StringBuilder();
                foreach (var command in args)
                {
                    // Escape any environment variables expressions in the command
                    // to prevent them from being interpreted by the docker compose CLI
                    EnvVarEscaper.EscapeUnescapedEnvVars(command, sb);
                    composeService.Command.Add(sb.ToString());
                    sb.Clear();
                }

View on GitHub (pinned to 25830f84bd)