What causes "Option %s requires a positive integer value" in sebastianbergmann/phpunit?

Pass a plain integer: `--diff-context=3`

sebastianbergmann/phpunit · error · Exception

Option %s requires a positive integer value

Error message

Option %s requires a positive integer value

What it means

requirePositiveIntValue() (src/TextUI/Configuration/Cli/Builder.php:1709) currently validates exactly one option: --diff-context (the context lines shown in failure diffs, Builder.php:1279). The first check fails when is_numeric() is false, i.e. the value is not even numeric. --diff-context accepts only an integer line count, not keywords or ranges.

Source

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

    {
        if ($value === null || $value === '') {
            throw new Exception(
                sprintf('Option %s requires a non-empty value', $option),
            );
        }

        return $value;
    }

    /**
     * @throws Exception
     *
     * @return positive-int
     */
    private function requirePositiveIntValue(?string $value, string $option): int
    {
        if (!is_numeric($value)) {
            throw new Exception(
                sprintf('Option %s requires a positive integer value', $option),
            );
        }

        $intValue = (int) $value;

        if ($intValue < 1) {
            throw new Exception(
                sprintf('Option %s requires a positive integer value', $option),
            );
        }

        return $intValue;
    }
}

View on GitHub (pinned to f123cdb2a2)

Solutions

Pass a plain integer: `--diff-context=3`
Check the env/CI variable that supplies the value and correct its type
Omit the flag to use PHPUnit's default context size

Example fix

# before
vendor/bin/phpunit --diff-context=auto

# after
vendor/bin/phpunit --diff-context=3

Defensive patterns

Strategy: validation

Validate before calling

$diffContext = getenv('PHPUNIT_DIFF_CONTEXT') ?: '3';

if (!is_numeric($diffContext)) {
    fwrite(STDERR, "--diff-context must be an integer, got: {$diffContext}" . PHP_EOL);
    exit(2);
}

$argv[] = '--diff-context=' . (int) $diffContext;

Try / catch

try {
    (new \PHPUnit\TextUI\CliArguments\Builder)->fromParameters($argv);
} catch (\PHPUnit\TextUI\CliArguments\Exception $e) {
    if (str_contains($e->getMessage(), 'requires a positive integer value')) {
        // fix the --diff-context value in whatever produced argv
    }
}

Prevention

--diff-context takes an integer line count only; there is no 'auto' or 'none' keyword
Type-check values sourced from env vars or CI templates before forwarding them
When in doubt, omit the option and accept the default

When it happens

Trigger: `vendor/bin/phpunit --diff-context=auto` (users expect a keyword); `--diff-context=3,5`; `--diff-context=none`; a value injected from an environment variable that contains a non-numeric string.

Common situations: Copying diff(1) or git diff -U semantics onto PHPUnit; CI configuration templating injecting a wrong type; documentation confusion about what --diff-context means.

Related errors

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