sebastianbergmann/phpunit · error · Exception

The path "%s" specified for the --log-events-verbose-text op

Error message

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

What it means

Same guard as for --log-events-text, but for --log-events-verbose-text, which enables the verbose test-runner event log (events plus payload data). Filesystem::resolveStreamOrFile() returns false when the value is not a php:// or socket:// stream and its parent directory does not exist, so PHPUnit aborts configuration building before the run starts.

Source

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

                    $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,
                            ),
                        );
                    }

                    break;

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

                    break;

                case '--with-telemetry':
                    $withTelemetry = true;

                    break;

View on GitHub (pinned to f123cdb2a2)

Solutions

Create the parent directory first: `mkdir -p .ci && vendor/bin/phpunit --log-events-verbose-text=.ci/events-verbose.txt`
Point at an existing directory (absolute path preferred in CI)
Use a stream target like `php://stderr` for temporary debugging sessions
Pre-validate from PHP: `is_dir(dirname($path)) || mkdir(dirname($path), 0777, true);` before invoking PHPUnit

Example fix

# before
vendor/bin/phpunit --log-events-verbose-text=.ci/events.txt   # .ci/ missing

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

Defensive patterns

Strategy: validation

Validate before calling

use function str_starts_with;

function verboseEventLogTargetResolves(string $path): bool
{
    return str_starts_with($path, 'php://')
        || str_starts_with($path, 'socket://')
        || is_dir(dirname($path));
}

$path = '.ci/events-verbose.txt';

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

Try / catch

try {
    $cliConfig = (new \PHPUnit\TextUI\CliArguments\Builder)->fromParameters($argv);
} catch (\PHPUnit\TextUI\CliArguments\Exception $e) {
    // covers unresolvable --log-events-verbose-text paths
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
    exit(1);
}

Prevention

Enable verbose event logging only when the target directory is guaranteed to exist (CI setup step)
Treat this option like any file output: check the parent directory before the run
Use a stream target during debugging sessions to avoid filesystem dependencies

When it happens

Trigger: `vendor/bin/phpunit --log-events-verbose-text=.ci/events-verbose.txt` where `.ci/` does not exist; a relative path evaluated from a working directory in which the parent directory is missing; typo'd directory component in the path. Stream targets (`php://stdout`, `socket://host:port`) bypass the directory check.

Common situations: Verbose event logging enabled for debugging in CI where the output directory is created by a later or skipped step; local scripts run from a different cwd after a project restructure; directory name typos (e.g. `.build` vs `build`).

Related errors

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