What causes "Error in bootstrap script: %s:%s%s%s%s" in sebastianbergmann/phpunit?

Read the embedded exception class, message and trace — they name the real failure inside the bootstrap script; fix that root cause.

sebastianbergmann/phpunit · error · BootstrapScriptException

Error in bootstrap script: %s:%s%s%s%s

Error message

Error in bootstrap script: %s:%s%s%s%s

What it means

After the readability check, BootstrapLoader::load() includes the bootstrap script inside a try/catch (Throwable). Any exception or error escaping the include — a thrown exception, a PHP 8 ParseError from a syntax error, a TypeError during setup — is rethrown as BootstrapScriptException('Error in bootstrap script: %s:%s%s%s%s') containing the exception class, its message, its stack trace, and one 'Previous error:' block per chained previous exception. The run aborts before any test executes.

Source

Thrown at src/TextUI/Configuration/BootstrapLoader.php:85

                $t->getMessage(),
                PHP_EOL,
                $t->getTraceAsString(),
            );

            while (($t = $t->getPrevious()) !== null) {
                $message .= sprintf(
                    '%s%sPrevious error: %s:%s%s%s%s',
                    PHP_EOL,
                    PHP_EOL,
                    $t::class,
                    PHP_EOL,
                    $t->getMessage(),
                    PHP_EOL,
                    $t->getTraceAsString(),
                );
            }

            throw new BootstrapScriptException($message);
        }

        EventFacade::emitter()->testRunnerBootstrapFinished($filename);
    }
}

View on GitHub (pinned to f123cdb2a2)

Solutions

Read the embedded exception class, message and trace — they name the real failure inside the bootstrap script; fix that root cause.
Lint the bootstrap to catch syntax errors quickly: php -l bootstrap.php.
Ensure everything the bootstrap needs (env vars, vendor dependencies, files) is present in the environment phpunit runs in.

Example fix

// before (bootstrap.php)
require __DIR__ . '/helpers/Env.php'; // throws: helpers/Env.php missing

// after (bootstrap.php)
if (!is_file(__DIR__ . '/helpers/Env.php')) {
    throw new RuntimeException('Run "composer install" before testing');
}
require __DIR__ . '/helpers/Env.php';

Defensive patterns

Strategy: try-catch

Validate before calling

# catch syntax errors before running the suite
php -l bootstrap.php

Try / catch

// when invoking the loader programmatically
use \PHPUnit\TextUI\Configuration\BootstrapScriptException;

try {
    $bootstrapLoader->handle($configuration);
} catch (BootstrapScriptException $e) {
    // message embeds the original exception class, message, trace and
    // 'Previous error' chains — surface it verbatim in CI logs and stop
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
    exit(1);
}

Prevention

Run php -l on the bootstrap in CI as a cheap parse check.
Keep bootstrap scripts small: only autoloading and constant/env setup; move real logic into testable classes.
Fail with clear messages from the bootstrap itself when required env vars or files are missing, so PHPUnit surfaces your text instead of a low-level error.

When it happens

Trigger: A syntax error in the bootstrap file; an exception thrown while the bootstrap registers autoloaders, constants, or environment setup; a missing dependency the bootstrap tries to use (e.g. referencing a vendor package that is not installed).

Common situations: Editing bootstrap.php and introducing a parse error; bootstrap code depending on env vars or files missing in CI; composer dependency updates that break bootstrap assumptions; PHP version mismatch making the bootstrap file unparsable.

Related errors

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