{"record":{"id":"8aeb49ce6f17fa9f","repo":"sebastianbergmann/phpunit","slug":"the-file-does-not-validate-against-any-known-schem","errorCode":null,"errorMessage":"The file does not validate against any known schema","messagePattern":"The file does not validate against any known schema","errorType":"validation","errorClass":"PHPUnit\\TextUI\\XmlConfiguration\\Exception","httpStatus":null,"severity":"error","filePath":"src/TextUI/Configuration/Xml/Migration/Migrator.php","lineNumber":37,"sourceCode":"\n/**\n * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit\n *\n * @internal This class is not covered by the backward compatibility promise for PHPUnit\n */\nfinal readonly class Migrator\n{\n    /**\n     * @throws Exception\n     * @throws MigrationException\n     * @throws XmlException\n     */\n    public function migrate(string $filename): string\n    {\n        $origin = (new SchemaDetector)->detect($filename);\n\n        if (!$origin->detected()) {\n            throw new Exception('The file does not validate against any known schema');\n        }\n\n        $configurationDocument = (new XmlLoader)->loadFile($filename);\n\n        if ($origin->version() === Version::series()) {\n            if (!$this->schemaLocationNeedsUpdate($configurationDocument)) {\n                throw new Exception('The file does not need to be migrated');\n            }\n\n            (new UpdateSchemaLocation)->migrate($configurationDocument);\n        } else {\n            foreach ((new MigrationBuilder)->build($origin->version()) as $migration) {\n                $migration->migrate($configurationDocument);\n            }\n        }\n\n        $configurationDocument->formatOutput       = true;\n        $configurationDocument->preserveWhiteSpace = false;","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/sebastianbergmann/phpunit/blob/f123cdb2a2d49f15025794166cfed8bda8627dd2/src/TextUI/Configuration/Xml/Migration/Migrator.php#L19-L55","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","solutions":["Check well-formedness first: `xmllint --noout phpunit.xml`","Remove custom/extension elements before migrating and re-add them afterwards","Confirm you are pointing at the actual phpunit.xml (`-c phpunit.xml`)","If the file is beyond repair, regenerate a fresh one with `--generate-configuration` and port settings over"],"exampleFix":"# before\nxmllint --noout phpunit.xml   # reports parser error -> migrate-configuration fails\n\n# after\n# fix the reported XML error, then\nvendor/bin/phpunit --migrate-configuration","handlingStrategy":"validation","validationCode":"// Pre-flight: well-formed XML before attempting migration\n$doc = new DOMDocument();\n\nif (!$doc->load('phpunit.xml')) {\n    fwrite(STDERR, \"phpunit.xml is not well-formed XML; fix parser errors first\" . PHP_EOL);\n    exit(2);\n}\n\n$result = (new \\PHPUnit\\TextUI\\XmlConfiguration\\SchemaDetector)->detect('phpunit.xml');\n\nif (!$result->detected()) {\n    fwrite(STDERR, 'File matches no PHPUnit schema; remove custom elements or repair the file' . PHP_EOL);\n    exit(2);\n}\n\n// safe to run --migrate-configuration","typeGuard":null,"tryCatchPattern":"try {\n    $migrated = (new \\PHPUnit\\TextUI\\XmlConfiguration\\Migration\\Migrator)->migrate('phpunit.xml');\n} catch (\\PHPUnit\\TextUI\\XmlConfiguration\\Exception $e) {\n    if (str_contains($e->getMessage(), 'does not validate against any known schema')) {\n        // repair well-formedness, strip custom elements, then retry migration\n    }\n}","preventionTips":["Run xmllint --noout on phpunit.xml after template/CI edits","Keep custom elements out of phpunit.xml (put extension config elsewhere) so schema detection works","Migrate right after each PHPUnit major upgrade instead of letting config drift across versions"],"tags":["phpunit","xml","migration","schema-detection","configuration"],"backgroundTag":"schema-detection-failed","analyzedSha":"f123cdb2a2d49f15025794166cfed8bda8627dd2","analyzedAt":"2026-08-23T01:20:58.058Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}