chocolatey/choco · error · ApplicationException

The '--order-by' clause '{0}' is not recognized. Use one of

Error message

The '--order-by' clause '{0}' is not recognized. Use one of the supported clauses:
 '{1}'.

What it means

Thrown during argument parsing for --order-by when the provided value (after unquoting) is non-empty but does not match any PackageOrder enum name via case-insensitive Enum.TryParse. The message lists the valid clause names formatted with quotes for clarity.

Source

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

                     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)
                         {
                             configuration.ListCommand.OrderByPopularity = true;

                             this.Log().Warn(
                                 @"'--order-by-popularity' is deprecated and will be removed in a future release.
 Use '--order-by='Popularity'' instead.");
                         }

View on GitHub (pinned to 0d5abdd10c)

Solutions

Read the error message — it lists all valid options quoted.
Use an exact valid value: 'choco search --order-by=Popularity'.
Run 'choco search --help' to see documented order-by options.

Example fix

// before
choco search --order-by=Date
// after
choco search --order-by=Popularity

Defensive patterns

Strategy: validation

Validate before calling

// Validate order-by is a known enum value
var validOptions = Enum.GetNames(typeof(PackageOrder));
if (!Enum.TryParse<PackageOrder>(orderBy, ignoreCase: true, out _))
{
    Console.Error.WriteLine($"Invalid --order-by '{orderBy}'. Valid: {string.Join(", ", validOptions)}");
}

Type guard

static bool IsValidOrderBy(string value) => Enum.TryParse<PackageOrder>(value, ignoreCase: true, out _);

Prevention

Check valid PackageOrder enum names before passing --order-by.
Read the error message which lists all valid options.

When it happens

Trigger: Running 'choco search --order-by=<invalid>' where <invalid> is not one of the PackageOrder enum values (e.g. 'choco search --order-by=Date' when no such enum member exists). The Enum.TryParse fails and the error lists valid options.

Common situations: User guesses a sort field name that does not exist. Version differences where an option name was renamed. Copying from outdated documentation.

Related errors

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