sebastianbergmann/phpunit · error · Exception

Options %s and %s cannot be used together

Error message

Options %s and %s cannot be used together

What it means

Thrown by the CLI Builder when more than one of PHPUnit's mutually exclusive command options is used. COMMAND_OPTIONS (src/TextUI/Configuration/Cli/Builder.php:239) is: --atleast-version, --check-php-configuration, --check-version, --generate-configuration, --help, --list-groups, --list-suites, --list-test-files, --list-test-ids, --list-tests, --list-tests-xml, --migrate-configuration, --validate-configuration, --version, --warm-coverage-cache. Each makes PHPUnit execute a single command and exit instead of running tests, so at most one can be honored. Note the separate CONFLICTING_OPTIONS pairs (e.g. --repeat with --retry, --no-output with --testdox) only emit a warning; the hard exception is reserved for combining two COMMAND_OPTIONS.

Source

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

                    sprintf(
                        'Options %s and %s cannot be used together',
                        $conflictingOptions[0],
                        $conflictingOptions[1],
                    ),
                );
            }
        }

        $usedCommandOptions = [];

        foreach (self::COMMAND_OPTIONS as $commandOption) {
            if (isset($this->processed[$commandOption])) {
                $usedCommandOptions[] = $commandOption;
            }
        }

        if (count($usedCommandOptions) > 1) {
            throw new Exception(
                sprintf(
                    'Options %s and %s cannot be used together',
                    $usedCommandOptions[0],
                    $usedCommandOptions[1],
                ),
            );
        }
    }

    /**
     * @return positive-int
     */
    private function parseStopOnValue(?string $value): int
    {
        if (is_numeric($value)) {
            return max(1, (int) $value);
        }

View on GitHub (pinned to f123cdb2a2)

Solutions

1. Split into separate PHPUnit invocations: `vendor/bin/phpunit --migrate-configuration && vendor/bin/phpunit --validate-configuration`
2. Echo or `bash -x` the expanded command to find which two command options are being combined
3. In wrappers, forward only the first command option and warn about any others

Example fix

# before
vendor/bin/phpunit --migrate-configuration --validate-configuration

# after
vendor/bin/phpunit --migrate-configuration
vendor/bin/phpunit --validate-configuration

const COMMAND_OPTIONS = [
    '--atleast-version', '--check-php-configuration', '--check-version',
    '--generate-configuration', '--help', '--list-groups', '--list-suites',
    '--list-test-files', '--list-test-ids', '--list-tests', '--list-tests-xml',
    '--migrate-configuration', '--validate-configuration', '--version',
    '--warm-coverage-cache',
];

$used = array_values(array_intersect($argv, COMMAND_OPTIONS));

if (count($used) > 1) {
    fwrite(STDERR, 'Refusing to run: ' . implode(' and ', array_slice($used, 0, 2)) . ' cannot be combined' . PHP_EOL);
    exit(2);
}

try {
    (new \PHPUnit\TextUI\CliArguments\Builder)->fromParameters($argv);
} catch (\PHPUnit\TextUI\CliArguments\Exception $e) {
    if (str_contains($e->getMessage(), 'cannot be used together')) {
        // split the run or drop one command option, then retry manually
    }
}

When it happens

Trigger: `vendor/bin/phpunit --migrate-configuration --validate-configuration`; `--list-tests --version`; `--generate-configuration --warm-coverage-cache`; wrapper scripts that concatenate flags (e.g. `phpunit $EXTRA_FLAGS $CMD`) where both variables expand to command options.

Common situations: CI pipelines that merge several maintenance invocations into one line; task-runner/IDE integrations that append their own flags to user-supplied ones; copy-pasted command lines that accumulate options over time.

Related errors

• Class %s cannot be found in %s
• unrecognized --order-by option: %s
• The path "%s" specified for the --log-events-text option cou
• The path "%s" specified for the --log-events-verbose-text op
• Option %s requires a non-empty value

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