PHP "Xdebug not loaded" for Coverage in CI

Line coverage needs an instrumentation driver. Xdebug only records coverage when it is both installed and xdebug.mode includes coverage. A runner with Xdebug missing, or with xdebug.mode=off, cannot produce a coverage report.

What this error means

A coverage command fails or produces no data, reporting that Xdebug is not loaded or not in coverage mode. A plain test run passes; only coverage is affected.

php

$ php vendor/bin/phpunit --coverage-text
Warning: XDEBUG_MODE=coverage (environment variable) or
xdebug.mode=coverage (PHP configuration setting) has to be set
No code coverage driver available

Common causes

Xdebug is not installed on the runner

A minimal image without Xdebug (and without pcov) has no coverage driver, so coverage cannot be collected.

Xdebug is loaded but not in coverage mode

Xdebug 3 records coverage only when xdebug.mode includes coverage. With off or debug, it is present but unusable for coverage.

How to fix it

Enable Xdebug coverage mode

Set the mode for the run via the environment variable.

php

XDEBUG_MODE=coverage php vendor/bin/phpunit --coverage-clover coverage.xml

Select a coverage driver in setup-php

Let setup-php enable Xdebug (or pcov, which is faster for coverage-only).

php

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    coverage: xdebug   # or pcov

Confirm the driver is active

Run php -m | grep -E "xdebug|pcov" to confirm a driver is loaded.
For Xdebug, check php -i | grep xdebug.mode includes coverage.
Prefer pcov when you only need coverage, not step debugging.

How to prevent it

Enable a coverage driver (Xdebug in coverage mode, or pcov) in coverage jobs only.
Keep coverage jobs separate so non-coverage runs stay fast without Xdebug overhead.
Assert the driver with php -m before running coverage.