sebastianbergmann/phpunit · error · PHPUnit\TextUI\XmlConfiguration\Exception

Cannot load XML configuration file %s

Error message

Cannot load XML configuration file %s

What it means

Thrown by the XML configuration Loader when a phpunit.xml cannot be loaded or does not validate against the bundled XML schema. When validation fails, PHPUnit appends every schema violation with line and column ('because it has validation errors:' followed by the validator output), and the original throwable is chained as the previous exception. This is the main error surface for a broken or outdated phpunit.xml/XML configuration file.

Source

Thrown at src/TextUI/Configuration/Xml/Loader.php:161

                $this->source($configurationFileRealpath, $xpath),
                $this->codeCoverage($configurationFileRealpath, $xpath),
                $this->groups($xpath),
                $this->logging($configurationFileRealpath, $xpath),
                $this->php($configurationFileRealpath, $xpath),
                $this->phpunit($configurationFileRealpath, $document, $xpath),
                $this->testSuite($configurationFileRealpath, $xpath),
            );
        } catch (Throwable $t) {
            $message = sprintf(
                'Cannot load XML configuration file %s',
                $configurationFileRealpath,
            );

            if ($validationResult->hasValidationErrors()) {
                $message .= ' because it has validation errors:' . PHP_EOL . $validationResult->asString();
            }

            throw new Exception($message, previous: $t);
        }
    }

    private function logging(string $filename, DOMXPath $xpath): Logging
    {
        $junit   = null;
        $element = $this->element($xpath, 'logging/junit');

        if ($element !== null) {
            $junit = new Junit(
                new File(
                    $this->toAbsolutePath(
                        $filename,
                        (string) $this->parseStringAttribute($element, 'outputFile'),
                    ),
                ),
            );
        }

View on GitHub (pinned to f123cdb2a2)

Solutions

1. Read the appended validation errors: they name each element/attribute and its line and column in the XML
2. Run `vendor/bin/phpunit --migrate-configuration` to auto-migrate an older file to the current schema
3. Validate quickly with `vendor/bin/phpunit --validate-configuration`
4. If hand-written, compare against vendor/phpunit/phpunit/phpunit.xsd or a freshly `--generate-configuration`-generated file

Example fix

<!-- before: PHPUnit 9 syntax read by PHPUnit 11+ -->
<filter>
  <whitelist>
    <directory suffix=".php">src</directory>
  </whitelist>
</filter>

<!-- after: migrate, or write current syntax -->
<!-- run: vendor/bin/phpunit --migrate-configuration -->
<source>
  <include>
    <directory suffix=".php">src</directory>
  </include>
</source>

// Fast pre-flight in CI before running tests:
$exit = 0;
system('vendor/bin/phpunit --validate-configuration', $exit);

if ($exit !== 0) {
    fwrite(STDERR, "phpunit.xml is invalid; refusing to run" . PHP_EOL);
    exit($exit);
}

// or schema-check directly:
// xmllint --noout --schema vendor/phpunit/phpunit/phpunit.xsd phpunit.xml

try {
    $configuration = (new \PHPUnit\TextUI\XmlConfiguration\Loader)->loadFile('phpunit.xml');
} catch (\PHPUnit\TextUI\XmlConfiguration\Exception $e) {
    // message includes each validation error with line/column; chain contains the original Throwable.
    // Run --migrate-configuration for version drift, or fix the named elements.
}

When it happens

Trigger: `vendor/bin/phpunit -c phpunit.xml` where the XML misspells elements (e.g. <testsuit>), puts attributes in wrong places, or uses elements removed/renamed in the installed PHPUnit major version; malformed XML (unclosed tags, bad entities); a configuration written for PHPUnit 9 (e.g. <filter><whitelist>) loaded by PHPUnit 11/12.

Common situations: Upgrading PHPUnit across major versions without migrating phpunit.xml; hand-editing the XML and introducing typos; extensions adding custom elements without proper schema handling; CI resolving a different PHPUnit version than local.

Related errors

• The file does not validate against any known schema
• The file does not need to be migrated
• Parameter "%s" does not exist
• Invalid version comparison operator: "%s"
• Default test suite is not configured

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