doctrine/orm · error · LogicException

The XML metadata driver cannot be enabled because the Simple

Error message

The XML metadata driver cannot be enabled because the SimpleXML PHP extension is missing. Please configure PHP with SimpleXML or choose a different metadata driver.

What it means

The XmlDriver parses Doctrine's .dcm.xml mapping files with SimpleXML, so its constructor hard-fails with a LogicException when the simplexml extension is not loaded, before any mapping work starts. The message tells you to either compile the extension into PHP or pick a different metadata driver.

Source

Thrown at src/Mapping/Driver/XmlDriver.php:57

 *
 * @template-extends FileDriver<SimpleXMLElement>
 */
class XmlDriver extends FileDriver
{
    use LoadMappingFileImplementation;

    public const DEFAULT_FILE_EXTENSION = '.dcm.xml';

    /**
     * {@inheritDoc}
     */
    public function __construct(
        string|array|FileLocator $locator,
        string $fileExtension = self::DEFAULT_FILE_EXTENSION,
        private readonly bool $isXsdValidationEnabled = true,
    ) {
        if (! extension_loaded('simplexml')) {
            throw new LogicException(
                'The XML metadata driver cannot be enabled because the SimpleXML PHP extension is missing.'
                . ' Please configure PHP with SimpleXML or choose a different metadata driver.',
            );
        }

        if ($isXsdValidationEnabled && ! extension_loaded('dom')) {
            throw new LogicException(
                'XSD validation cannot be enabled because the DOM extension is missing.',
            );
        }

        parent::__construct($locator, $fileExtension);
    }

    /**
     * {@inheritDoc}
     *
     * @param class-string<T>  $className

View on GitHub (pinned to d9b9ff7301)

Solutions

1. Install/enable the extension: docker-php-ext-install simplexml (Docker), apt install php-xml (Debian/Ubuntu), apk add php83-simplexml (Alpine), then restart PHP-FPM/CLI.
2. Verify with php -m | grep -i simplexml before deploying.
3. If you cannot change the runtime, switch the project to the AttributeDriver (attributes) so no XML parsing is needed.

Example fix

# before (Dockerfile)
FROM php:8.3-cli
# XmlDriver throws: SimpleXML missing

# after
FROM php:8.3-cli
RUN docker-php-ext-install simplexml dom

if (! extension_loaded('simplexml')) {
    throw new RuntimeException('XML mappings require ext-simplexml; install it or use the AttributeDriver.');
}
$driver = new XmlDriver($locator);

When it happens

Trigger: Instantiating new XmlDriver($locator) on a PHP build without ext-simplexml — typically slim Docker images (alpine php:8*-cli without docker-php-ext-install simplexml) or distro PHP installs where the php-xml package was never installed.

Common situations: Alpine/slim production or CI images; php:fpm images where only selected extensions were enabled; hardened hosting where simplexml is disabled; switching a project to XML mappings on a server provisioned for attribute mappings.

Related errors

• XSD validation cannot be enabled because the DOM extension i
• Uninitialized result set mapping.
• Unable to use access strategy type of [%s] without a Concurr
• Unrecognized access strategy type [%s]
• If you want to use a "READ_WRITE" cache an implementation of

AI-assisted analysis of doctrine/orm@d9b9ff7301 (2026-08-21). Data as JSON: /api/errors/0920beea77797ab3. Report an issue: GitHub.