sebastianbergmann/phpunit · error · CodeCoverageDriverException

Configured code coverage driver class "%s" does not exist

Error message

Configured code coverage driver class "%s" does not exist

What it means

phpunit.xml configures a custom code coverage driver via the driver attribute of the <coverage> element (parsed by the XML configuration loader). When coverage is activated, PHPUnit tries to load that class and class_exists() failed — the FQCN is misspelled, its package is not installed or autoloadable, or an extension it depends on is missing. The CodeCoverageDriverException aborts coverage initialization.

Source

Thrown at src/Runner/CodeCoverage.php:608

            $this->collectsPathCoverage   = $pathCoverage;
        } catch (CodeCoverageException $e) {
            $message = $e->getMessage();

            if ($message === '') {
                $message = 'Code coverage cannot be initialized';
            }

            EventFacade::emitter()->testRunnerTriggeredPhpunitWarning($message);
        }
    }

    /**
     * @phpstan-ignore return.internalClass
     */
    private function instantiateDriver(string $driverClass, Filter $filter, Granularity $granularity): Driver
    {
        if (!class_exists($driverClass)) {
            throw new CodeCoverageDriverException(
                sprintf(
                    'Configured code coverage driver class "%s" does not exist',
                    $driverClass,
                ),
            );
        }

        /** @phpstan-ignore classConstant.internalClass */
        if (!is_subclass_of($driverClass, Driver::class)) {
            throw new CodeCoverageDriverException(
                sprintf(
                    'Configured code coverage driver class "%s" does not extend %s',
                    $driverClass,
                    /** @phpstan-ignore classConstant.internalClass */
                    Driver::class,
                ),
            );
        }

View on GitHub (pinned to f123cdb2a2)

Solutions

1. Check the exact FQCN in the driver attribute against the class's namespace and spelling.
2. Ensure the package providing the driver is installed and autoloaded (composer install, composer dump-autoload).
3. Verify quickly in the same environment: php -r 'var_dump(class_exists("App\\Coverage\\MyDriver"));'.
4. If you do not need a custom driver, remove the driver attribute so PHPUnit auto-selects Xdebug/PCOV.

Example fix

<!-- before -->
<coverage driver="App\Covrage\MyDriver"/>

<!-- after -->
<coverage driver="App\Coverage\MyDriver"/>

// Preflight the driver attribute before running with coverage
$class = 'App\\Coverage\\MyDriver'; // read from phpunit.xml in practice
if (!class_exists($class)) {
    fwrite(STDERR, "Coverage driver {$class} does not exist; check the <coverage driver=...> setting\n");
    exit(1);
}

When it happens

Trigger: <coverage driver="App\Coverage\MyDriver"> where that class does not exist — typo, wrong namespace, the composer package providing it not required, or a phar/extension not loaded in the current environment.

Common situations: Custom drivers (e.g., wrapping a vendor-specific collector) referenced before the package was added; refactors renaming driver classes; case or leading-backslash mistakes in the FQCN; CI missing a PHP extension the driver class file depends on.

Related errors

• Configured code coverage driver class "%s" does not extend %
• Configured code coverage driver class "%s" is not instantiab
• Cannot read baseline %s, file does not exist
• Subscriber "%s" does not implement any known interface - did
• Unknown event type "%s"

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