chocolatey/choco · error · ApplicationException

A single config command must be listed. Please see the help

Error message

A single config command must be listed. Please see the help menu for those commands.

What it means

The config command allows a single positional subcommand/argument. ParseAdditionalArguments throws when unparsedArguments.Count > 1 while the command is List or a name was already resolved, because multiple leftover positional tokens are ambiguous. It points the user to the help menu for valid single config commands (list/get/set/unset).

Source

Thrown at src/chocolatey/infrastructure.app/commands/ChocolateyConfigCommand.cs:80

            Enum.TryParse(unparsedCommand, true, out command);
            if (command == ConfigCommandType.Unknown)
            {
                if (!string.IsNullOrWhiteSpace(unparsedCommand))
                {
                    this.Log().Warn("Unknown command {0}. Setting to list.".FormatWith(unparsedCommand));
                }

                command = ConfigCommandType.List;
            }

            configuration.ConfigCommand.Command = command;

            if ((configuration.ConfigCommand.Command == ConfigCommandType.List
                 || !string.IsNullOrWhiteSpace(configuration.ConfigCommand.Name)
                )
                && unparsedArguments.Count > 1)
            {
                throw new ApplicationException("A single config command must be listed. Please see the help menu for those commands.");
            }

            if (string.IsNullOrWhiteSpace(configuration.ConfigCommand.Name) && unparsedArguments.Count >= 2)
            {
                configuration.ConfigCommand.Name = unparsedArguments[1];
            }
            if (string.IsNullOrWhiteSpace(configuration.ConfigCommand.ConfigValue) && unparsedArguments.Count >= 3)
            {
                configuration.ConfigCommand.ConfigValue = unparsedArguments[2];
            }
        }

        public virtual void Validate(ChocolateyConfiguration configuration)
        {
            if (configuration.ConfigCommand.Command != ConfigCommandType.List && string.IsNullOrWhiteSpace(configuration.ConfigCommand.Name))
            {
                throw new ApplicationException("When specifying the subcommand '{0}', you must also specify --name by option or position.".FormatWith(configuration.ConfigCommand.Command.ToStringSafe().ToLower()));
            }

View on GitHub (pinned to 0d5abdd10c)

Solutions

Pass a single config subcommand and use --name/--value (or at most two positional tokens: name, value).
Run 'choco config -?' to see the supported subcommands.
Quote compound values and verify the count of leftover positionals.

Example fix

# before
choco config set cacheLocation C:\cache extra

# after
choco config set --name cacheLocation --value C:\cache

Defensive patterns

Strategy: validation

Validate before calling

// Config takes at most one subcommand (+ up to two positional name/value).
var positional = tokens.Where(t => !t.StartsWith("-")).ToList();
if (positional.Count > 3)
{
    throw new ArgumentException("config: too many positional arguments");
}

Prevention

Prefer --name/--value flags over positional tokens to avoid count errors.
Run 'choco config -?' to learn the supported subcommands.

When it happens

Trigger: Running 'choco config get extra', 'choco config set name value extra', or any config invocation leaving more than one unparsed positional token.

Common situations: Treating config like install (multiple names); quoting/parsing errors leaving stray tokens; positional value supplied alongside a name in list mode.

Related errors

AI-assisted analysis of chocolatey/choco@0d5abdd10c (2026-08-13). Data as JSON: /api/errors/e97a1f067542fd27. Report an issue: GitHub.