sebastianbergmann/phpunit · error · Exception

The path "%s" specified for the --log-events-text option cou

Error message

The path "%s" specified for the --log-events-text option could not be resolved

What it means

PHPUnit throws this while building the CLI configuration when the value of --log-events-text is neither a php:// or socket:// stream nor a path whose parent directory exists. Filesystem::resolveStreamOrFile() (src/Util/Filesystem.php:37) returns false exactly when dirname($path) is not an existing directory, and the Builder converts that into this exception. PHPUnit refuses to start because it cannot determine where the test-runner event log should be written; it does not create missing parent directories for this option.

Source

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

                    break;

                case '--ignore-dependencies':
                    $resolveDependencies = false;

                    break;

                case '--reverse-order':
                    $executionOrder = TestSuiteSorter::ORDER_REVERSED;

                    break;

                case '--log-events-text':
                    $logEventsTextPath = $this->requireNonEmptyValue($option[1], '--log-events-text');
                    $logEventsText     = Filesystem::resolveStreamOrFile($logEventsTextPath);

                    if ($logEventsText === false) {
                        throw new Exception(
                            sprintf(
                                'The path "%s" specified for the --log-events-text option could not be resolved',
                                $logEventsTextPath,
                            ),
                        );
                    }

                    break;

                case '--log-events-verbose-text':
                    $logEventsVerboseTextPath = $this->requireNonEmptyValue($option[1], '--log-events-verbose-text');
                    $logEventsVerboseText     = Filesystem::resolveStreamOrFile($logEventsVerboseTextPath);

                    if ($logEventsVerboseText === false) {
                        throw new Exception(
                            sprintf(
                                'The path "%s" specified for the --log-events-verbose-text option could not be resolved',
                                $logEventsVerboseTextPath,

View on GitHub (pinned to f123cdb2a2)

Solutions

Create the parent directory before running: `mkdir -p build && vendor/bin/phpunit --log-events-text=build/events.txt`
Use a path whose parent directory already exists, ideally an absolute path
Use a stream wrapper such as `--log-events-text=php://stderr` or `php://stdout` when you do not need a file
When invoking the runner from PHP, pre-check `is_dir(dirname($path))` and create the directory (or drop the option) before building the configuration

Example fix

# before
vendor/bin/phpunit --log-events-text=build/events.txt   # build/ does not exist

# after
mkdir -p build
vendor/bin/phpunit --log-events-text=build/events.txt

# alternative (no file needed)
vendor/bin/phpunit --log-events-text=php://stderr

Defensive patterns

Strategy: validation

Validate before calling

use function str_starts_with;

function eventLogTargetResolves(string $path): bool
{
    if (str_starts_with($path, 'php://') || str_starts_with($path, 'socket://')) {
        return true;
    }

    return is_dir(dirname($path));
}

// before shelling out / building CLI configuration:
$path = 'build/events.txt';

if (!eventLogTargetResolves($path)) {
    mkdir(dirname($path), 0777, true);
}

// safe: --log-events-text=$path

Try / catch

try {
    $cliConfig = (new \PHPUnit\TextUI\CliArguments\Builder)->fromParameters($_SERVER['argv']);
} catch (\PHPUnit\TextUI\CliArguments\Exception $e) {
    // configuration-time failures, including unresolvable --log-events-text paths
    fwrite(STDERR, 'phpunit configuration error: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

Prevention

In CI, create output directories in a setup step: mkdir -p before running phpunit
Prefer php://stderr or php://stdout for ad-hoc event logging so no filesystem is involved
When wrapping PHPUnit in scripts, validate every file-output option with is_dir(dirname($path)) before exec

When it happens

Trigger: Running `vendor/bin/phpunit --log-events-text=build/events.txt` when `build/` does not exist; a relative or bare path whose parent directory was deleted or never created; a path like `/tmp/missing-dir/events.log` with an absent intermediate directory. Values prefixed with php:// or socket://, or paths whose dirname exists (the file itself may not exist yet), resolve fine.

Common situations: CI jobs writing event logs into directories that are not committed to the repo and never mkdir'd; scripts moved to a different working directory so a relative path no longer resolves; users assuming PHPUnit creates output directories like some coverage report targets do.

Related errors

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