What causes "unrecognized --order-by option: %s" in sebastianbergmann/phpunit?

sebastianbergmann/phpunit · error · Exception

unrecognized --order-by option: %s

Error message

unrecognized --order-by option: %s

What it means

Cli Builder::fromParameters() parses --order-by as a comma-separated list (explode(',', $option[1])) and each element must be one of: default, defects, depends, duration (deprecated), duration-ascending, duration-descending, no-depends, random, reverse, size (deprecated), size-ascending, size-descending. Any other element throws Exception('unrecognized --order-by option: %s') and aborts configuration building before tests run.

Source

Thrown at src/TextUI/Configuration/Cli/Builder.php:903

                                EventFacade::emitter()->testRunnerTriggeredPhpunitDeprecation(
                                    'Using "size" for --order-by is deprecated and will be removed in PHPUnit 14. Use "size-ascending" instead.',
                                );

                                break;

                            case 'size-ascending':
                                $executionOrder = TestSuiteSorter::ORDER_SIZE_ASCENDING;

                                break;

                            case 'size-descending':
                                $executionOrder = TestSuiteSorter::ORDER_SIZE_DESCENDING;

                                break;

                            default:
                                throw new Exception(
                                    sprintf(
                                        'unrecognized --order-by option: %s',
                                        $order,
                                    ),
                                );
                        }
                    }

                    break;

                case '--process-isolation':
                    $processIsolation = true;

                    break;

                case '--stderr':
                    $stderr = true;

View on GitHub (pinned to f123cdb2a2)

Solutions

Use a valid value: default, defects, depends, duration-ascending, duration-descending, no-depends, random, reverse, size-ascending, size-descending.
When combining orders, check every comma-separated element for typos, e.g. --order-by defects,duration-ascending.
Replace deprecated aliases duration/size with duration-ascending/size-ascending to stay future-proof.

Example fix

# before
phpunit --order-by randome tests
# => unrecognized --order-by option: randome

# after
phpunit --order-by random tests

Defensive patterns

Strategy: validation

Validate before calling

$allowed = [
    'default', 'defects', 'depends',
    'duration', 'duration-ascending', 'duration-descending',
    'no-depends', 'random', 'reverse',
    'size', 'size-ascending', 'size-descending',
];

foreach (explode(',', $orderBy) as $value) {
    if (!in_array(trim($value), $allowed, true)) {
        throw new InvalidArgumentException("Invalid --order-by value '{$value}'; allowed: " . implode(', ', $allowed));
    }
}

Prevention

Centralize CLI flags in a CI template or composer script instead of repeating them per job, so typos surface once.
Validate user-supplied ordering options against the allow-list above before shelling out to phpunit.
Re-check flag values when upgrading PHPUnit; aliases like 'duration'/'size' are deprecated in favor of duration-ascending/size-ascending.

When it happens

Trigger: Passing --order-by an unknown or misspelled value, e.g. --order-by=randome, --order-by=speed, or --order-by=default, defcts (a typo in one element of a list fails the whole option).

Common situations: Typos in CI pipeline flags; scripts written for other runners (e.g. --order-by=failed-first habits); using values removed or renamed between PHPUnit versions ('duration'/'size' still work but are deprecated in favor of duration-ascending/size-ascending).

Related errors

AI-assisted analysis of sebastianbergmann/phpunit@f123cdb2a2 (2026-08-23). Data as JSON: /api/errors/178df3596596ede2. Report an issue: GitHub.