chocolatey/choco · error · ApplicationException

No '--order-by' clause was provided. Specify one of the supp

Error message

No '--order-by' clause was provided. Specify one of the supported clauses:
 '{0}'.

What it means

Thrown during argument parsing for the --order-by option on the search/list command when the option value is present but empty or whitespace after unquoting. The option handler builds a list of valid PackageOrder enum names and includes them in the message. This is a parse-time error, not a validate-time error — it fires inside the lambda registered with the --order-by option.

Source

Thrown at src/chocolatey/infrastructure.app/commands/ChocolateySearchCommand.cs:118

                     "ByIdOnly - Only return packages where the id contains the search filter.",
                     option => configuration.ListCommand.ByIdOnly = option != null)
                 .Add("by-tag-only|by-tags-only",
                     "ByTagOnly - Only return packages where the search filter matches on the tags.",
                     option => configuration.ListCommand.ByTagOnly = option != null)
                 .Add("id-starts-with",
                     "IdStartsWith - Only return packages where the id starts with the search filter.",
                     option => configuration.ListCommand.IdStartsWith = option != null)
                 .Add("order-by=",
                     "OrderBy - Sort package results by Id (default), {0}. Available in 2.5.0+.".FormatWith(string.Join(", ", Enum.GetNames(typeof(PackageOrder)).Where(n => !n.IsEqualTo("Id")))),
                     option =>
                     {
                        var validOptions = Enum.GetNames(typeof(PackageOrder));
                         var formattedOptions = string.Join("', '", validOptions);
                         var unquotedOption = option.UnquoteSafe();

                         if (string.IsNullOrWhiteSpace(unquotedOption))
                         {
                             throw new ApplicationException(
                                @"No '--order-by' clause was provided. Specify one of the supported clauses:
 '{0}'.".FormatWith(formattedOptions));
                         }

                         if (!Enum.TryParse(unquotedOption, ignoreCase: true, out PackageOrder orderBy))
                         {
                            throw new ApplicationException(
                                @"The '--order-by' clause '{0}' is not recognized. Use one of the supported clauses:
 '{1}'.".FormatWith(unquotedOption, formattedOptions));
                         }

                         configuration.ListCommand.OrderBy = orderBy;
                 })
                 .Add("order-by-popularity",
                     "(Deprecated) OrderByPopularity - Sort package results by popularity. Use '--order-by='Popularity'' instead.",
                     option =>
                     {
                         if (option != null)

View on GitHub (pinned to 0d5abdd10c)

Solutions

Provide a valid sort clause from the PackageOrder enum: 'choco search --order-by=Popularity'.
If the sort value comes from a variable, ensure it is non-empty before passing, or omit --order-by entirely to use the default (Id).
Check valid options via the error message itself, which lists them.

Example fix

// before
choco search --order-by=
// after
choco search --order-by=Popularity
// or omit entirely for default Id ordering
choco search

Defensive patterns

Strategy: validation

Validate before calling

// Validate order-by is non-empty before calling search
if (!string.IsNullOrWhiteSpace(orderBy) && orderBy.UnquoteSafe().Trim() == "")
{
    Console.Error.WriteLine("--order-by value is empty. Valid options: Id, Popularity, ...");
}

Prevention

Omit --order-by entirely to use the default (Id) instead of passing an empty value.
Ensure script variables backing --order-by are non-empty.

When it happens

Trigger: Running 'choco search --order-by=' (empty value) or 'choco search --order-by=""' (quoted empty string). The UnquoteSafe() call produces an empty string, which fails the IsNullOrWhiteSpace check.

Common situations: Script or CI pipeline sets --order-by from a variable that is unexpectedly empty. User accidentally types the flag with no value. Available since Chocolatey 2.5.0+.

Related errors

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