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

The file does not validate against any known schema

Error message

The file does not validate against any known schema

What it means

Migrator::migrate() (used by `phpunit --migrate-configuration`) first runs SchemaDetector over the file; if it does not validate against any PHPUnit schema version known to the installed PHPUnit, migration is impossible and this exception is thrown. Common causes are malformed XML, custom/unknown elements that no schema allows, or passing the wrong file.

Source

Thrown at src/TextUI/Configuration/Xml/Migration/Migrator.php:37

/**
 * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
 *
 * @internal This class is not covered by the backward compatibility promise for PHPUnit
 */
final readonly class Migrator
{
    /**
     * @throws Exception
     * @throws MigrationException
     * @throws XmlException
     */
    public function migrate(string $filename): string
    {
        $origin = (new SchemaDetector)->detect($filename);

        if (!$origin->detected()) {
            throw new Exception('The file does not validate against any known schema');
        }

        $configurationDocument = (new XmlLoader)->loadFile($filename);

        if ($origin->version() === Version::series()) {
            if (!$this->schemaLocationNeedsUpdate($configurationDocument)) {
                throw new Exception('The file does not need to be migrated');
            }

            (new UpdateSchemaLocation)->migrate($configurationDocument);
        } else {
            foreach ((new MigrationBuilder)->build($origin->version()) as $migration) {
                $migration->migrate($configurationDocument);
            }
        }

        $configurationDocument->formatOutput       = true;
        $configurationDocument->preserveWhiteSpace = false;

View on GitHub (pinned to f123cdb2a2)

Solutions

1. Check well-formedness first: `xmllint --noout phpunit.xml`
2. Remove custom/extension elements before migrating and re-add them afterwards
3. Confirm you are pointing at the actual phpunit.xml (`-c phpunit.xml`)
4. If the file is beyond repair, regenerate a fresh one with `--generate-configuration` and port settings over

Example fix

# before
xmllint --noout phpunit.xml   # reports parser error -> migrate-configuration fails

# after
# fix the reported XML error, then
vendor/bin/phpunit --migrate-configuration

// Pre-flight: well-formed XML before attempting migration
$doc = new DOMDocument();

if (!$doc->load('phpunit.xml')) {
    fwrite(STDERR, "phpunit.xml is not well-formed XML; fix parser errors first" . PHP_EOL);
    exit(2);
}

$result = (new \PHPUnit\TextUI\XmlConfiguration\SchemaDetector)->detect('phpunit.xml');

if (!$result->detected()) {
    fwrite(STDERR, 'File matches no PHPUnit schema; remove custom elements or repair the file' . PHP_EOL);
    exit(2);
}

// safe to run --migrate-configuration

try {
    $migrated = (new \PHPUnit\TextUI\XmlConfiguration\Migration\Migrator)->migrate('phpunit.xml');
} catch (\PHPUnit\TextUI\XmlConfiguration\Exception $e) {
    if (str_contains($e->getMessage(), 'does not validate against any known schema')) {
        // repair well-formedness, strip custom elements, then retry migration
    }
}

When it happens

Trigger: `vendor/bin/phpunit --migrate-configuration` where phpunit.xml is not well-formed XML; the root element or children use namespaces/custom tags unknown to every bundled schema; -c pointing at some other XML file (e.g. a pom or Ant build file).

Common situations: Trying to migrate a heavily customized or already-corrupted configuration; XML with unescaped ampersands/invalid entities; files assembled by templating engines leaving artifacts; passing a directory or wrong filename.

Related errors

• Cannot load XML configuration file %s
• 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/8aeb49ce6f17fa9f. Report an issue: GitHub.