Application crashes with ReflectionException when oro_entity_config contains stale class references (missing PHP classes after branch switch)

[Genaker]

Summary

php bin/console cache:clear crashes with a ReflectionException when the oro_entity_config
database table contains entity class names that no longer exist as PHP files.
This happens naturally when switching git branches where different bundles are present.
The error completely blocks cache clearing with no hint about the cause or fix.

Steps to reproduce

1. Install Oro with a custom bundle (e.g. AcmeShipmentBundle) that has entities registered
   in oro_entity_config via migrations
2. Switch to a git branch that does not include that bundle
3. Run composer dump-autoload
4. Run php bin/console cache:clear

Actual Result

Cache clear aborts with:

In AbstractManagerRegistry.php line 175:

  Class "Acme\Bundle\ShipmentBundle\Entity\Delivery" does not exist

Full stack trace:

ReflectionClass->__construct()
  at vendor/doctrine/persistence/src/Persistence/AbstractManagerRegistry.php:175
Doctrine\Persistence\AbstractManagerRegistry->getManagerForClass()
  at vendor/oro/platform/src/Oro/Bundle/EntityBundle/ORM/Registry.php:79
Oro\Bundle\EntityBundle\ORM\Registry->getManagerForClass()
  at vendor/oro/marketing/src/Oro/Bundle/MarketingListBundle/Provider/ContactInformationExclusionProvider.php:56
Oro\Bundle\MarketingListBundle\Provider\ContactInformationExclusionProvider->isIgnoredEntity()
  at vendor/oro/platform/src/Oro/Bundle/EntityBundle/Provider/ChainExclusionProvider.php:37
Oro\Bundle\EntityBundle\Provider\ChainExclusionProvider->isIgnoredEntity()
  at vendor/oro/marketing/src/Oro/Bundle/MarketingActivityBundle/Provider/MarketingActivityVirtualRelationProvider.php:66
Oro\Bundle\MarketingActivityBundle\Provider\MarketingActivityVirtualRelationProvider->getVirtualRelations()
  at vendor/oro/platform/src/Oro/Bundle/EntityBundle/Provider/ChainVirtualRelationProvider.php:56
Oro\Bundle\EntityBundle\Provider\ChainVirtualRelationProvider->getVirtualRelations()
  at vendor/oro/platform/src/Oro/Bundle/EntityConfigBundle/Config/ConfigCacheWarmer.php:285
Oro\Bundle\EntityConfigBundle\Config\ConfigCacheWarmer->loadVirtualFields()
  at vendor/oro/platform/src/Oro/Bundle/EntityConfigBundle/Config/ConfigCacheWarmer.php:93
Oro\Bundle\EntityConfigBundle\Config\ConfigCacheWarmer->warmUpCache()
  at vendor/oro/platform/src/Oro/Bundle/EntityConfigBundle/Cache/CacheWarmer.php:21

Root cause: ConfigCacheWarmer::loadVirtualFields() iterates every class in oro_entity_config
and calls Registry::getManagerForClass($class) on each one.
That method delegates to AbstractManagerRegistry which calls new ReflectionClass($class)
with no class_exists() guard. When $class no longer exists, PHP throws a
ReflectionException and aborts the entire warmup.

// Oro\Bundle\EntityBundle\ORM\Registry — no guard before delegating to parent
public function getManagerForClass($class)
{
    if (\array_key_exists($class, $this->managersMap)) {
        return $this->cachedManagers[$this->managersMap[$class]];
    }
    $manager = parent::getManagerForClass($class); // crashes if class is missing
    ...
}

// Doctrine\Persistence\AbstractManagerRegistry — detonator
public function getManagerForClass(string $class)
{
    $proxyClass = new ReflectionClass($class); // ReflectionException if class gone
    ...
}

Expected Result

cache:clear should complete successfully.
A class that no longer exists has no Doctrine manager — getManagerForClass() should
return null for it (consistent with its existing contract for unknown classes)
rather than throwing.

Suggested fix in Oro\Bundle\EntityBundle\ORM\Registry::getManagerForClass():

public function getManagerForClass($class)
{
    if (\array_key_exists($class, $this->managersMap)) {
        return $this->cachedManagers[$this->managersMap[$class]];
    }

    // Guard: oro_entity_config is DB-driven and can contain stale class references
    // (e.g. after switching git branches or removing a bundle).
    // Return null instead of crashing — no manager exists for a non-existent class.
    if (!class_exists($class) && !interface_exists($class, false)) {
        $this->managersMap[$class] = '';
        $this->cachedManagers[''] = null;
        return null;
    }

    $manager = parent::getManagerForClass($class);
    $hash    = null !== $manager ? spl_object_hash($manager) : '';
    $this->managersMap[$class]   = $hash;
    $this->cachedManagers[$hash] = $manager;

    return $manager;
}

This fix belongs in Oro\Bundle\EntityBundle\ORM\Registry (Oro's own code, not Doctrine)
because Oro drives getManagerForClass() from a database-sourced class list
(oro_entity_config) that can legitimately contain stale references.
Doctrine's expectation that callers pass valid class names is reasonable;
Oro must guard its own DB-driven usage.

Details about your environment

• OroPlatform version: 6.1.0
• PHP version: 8.2
• Database: PostgreSQL 14

Additional information

Workaround until fixed — remove the stale rows manually:

SELECT id, class_name FROM oro_entity_config WHERE class_name LIKE '%RemovedBundleName%';
DELETE FROM oro_entity_config WHERE class_name LIKE '%RemovedBundleName%';

Then: composer dump-autoload && php bin/console cache:clear

This issue affects any developer doing routine branch switching across feature branches
that add or remove bundles — a very common workflow on multi-team Oro projects.

[mbessolov]

OroPlatform does not perform automatic, silent upgrades or downgrades during a mere cache warmup based solely on changes in the PHP code.

It is the responsibility of the developer to ensure that the database state is synchronized with the codebase. This typically involves running oro:platform:update, reinstalling the application, or restoring a database dump that matches the current branch.

Cache warmup and cache:clear are not designed to detect or repair such inconsistencies automatically and should not be relied upon for that purpose.

If entity removal is an intentional part of an upgrade, it must be handled explicitly as part of that upgrade process. In particular, developers should implement an extend entity cache warmer to clean up or reconcile entity configuration accordingly (see ExtendEntityCacheWarmer.php for reference).

[Genaker]

Can it be at least proper Exception message for easy fix of the issue. Not just something went wrong.

[mbessolov]

I see your point, and improving the developer experience here is reasonable to consider.

At the same time, the current exception message is already quite explicit about the immediate problem:

In AbstractManagerRegistry.php line 175:

Class "Acme\Bundle\ShipmentBundle\Entity\Delivery" does not exist

It clearly indicates that the system is trying to work with a class that is not present in the codebase.

What it does not provide is additional context about why this might happen (e.g., stale configuration after a branch switch) or suggested remediation steps. That is where an improvement could be made.

If you have a specific suggestion for how the message should be extended to make this clearer, that would help us evaluate and refine it.

[Genaker]

@mbessolov

Thanks for reopening. Here is a concrete suggestion for the message improvement.

The current error surfaces from AbstractManagerRegistry (Doctrine internals) with no Oro
context about why the class is missing. The fix is a single try/catch in
ConfigCacheWarmer::loadVirtualFields() . Oro's own code with no change to cache:clear
semantics:

// Oro\Bundle\EntityConfigBundle\Config\ConfigCacheWarmer  ~line 285
// inside the loop that calls getVirtualRelations() per entity class

try {
    $relations = $this->virtualRelationProvider->getVirtualRelations($class);
} catch (\ReflectionException $e) {
    throw new \RuntimeException(sprintf(
        "Cache warmup aborted: class \"%s\" is listed in oro_entity_config\n" .
        "but does not exist in the current codebase.\n\n" .
        "This typically happens after switching git branches where a bundle was\n" .
        "added or removed, or after deleting bundle files without running\n" .
        "oro:platform:update.\n\n" .
        "To identify and remove stale rows:\n\n" .
        "  SELECT class_name FROM oro_entity_config WHERE class_name = '%s';\n" .
        "  DELETE FROM oro_entity_config WHERE class_name = '%s';\n\n" .
        "Then re-run:\n\n" .
        "  composer dump-autoload\n" .
        "  php bin/console cache:clear",
        $class, $class, $class
    ), 0, $e);
}

The original ReflectionException is passed as the third constructor argument so the full
stack trace is preserved.

The only user-visible change: instead of

In AbstractManagerRegistry.php line 175:
  Class "Acme\Bundle\ShipmentBundle\Entity\Delivery" does not exist

the developer sees the class name, the reason, and the exact SQL + CLI steps to unblock
themselves — without Oro silently mutating the database or changing cache:clear behaviour.

---

A bin/console oro:entity-config:debug:stale command would replace the raw SQL step entirely
and is the natural next step, but the message change above is the minimum viable improvement.

---

Bonus: oro:entity-config:debug:stale command sketch

// src/Oro/Bundle/EntityConfigBundle/Command/DebugStaleEntityConfigCommand.php

#[AsCommand(name: 'oro:entity-config:debug:stale')]
class DebugStaleEntityConfigCommand extends Command
{
    public function __construct(private readonly ConfigManager $configManager)
    {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this
            ->setDescription('Lists oro_entity_config entries whose class no longer exists.')
            ->addOption('remove', null, InputOption::VALUE_NONE, 'Delete stale entries from the database.');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $stale = [];
        foreach ($this->configManager->getEntityConfigs() as $config) {
            $class = $config->getId()->getClassName();
            if (!class_exists($class) && !interface_exists($class, false)) {
                $stale[] = $class;
            }
        }

        if (empty($stale)) {
            $output->writeln('<info>No stale entity config entries found.</info>');
            return Command::SUCCESS;
        }

        $output->writeln(sprintf('<comment>Found %d stale entry/entries:</comment>', count($stale)));
        foreach ($stale as $class) {
            $output->writeln("  $class");
        }

        if ($input->getOption('remove')) {
            foreach ($stale as $class) {
                $this->configManager->clearEntityConfigCache($class);
                // remove from oro_entity_config via DBAL
            }
            $this->configManager->flush();
            $output->writeln('<info>Stale entries removed. Re-run cache:clear.</info>');
        } else {
            $output->writeln('');
            $output->writeln('Run with <comment>--remove</comment> to delete these entries, then:');
            $output->writeln('  composer dump-autoload && php bin/console cache:clear');
        }

        return Command::SUCCESS;
    }
}

Example output:

$ bin/console oro:entity-config:debug:stale

Found 2 stale entry/entries:
  Acme\Bundle\ShipmentBundle\Entity\Delivery
  Acme\Bundle\ShipmentBundle\Entity\DeliveryItem

Run with --remove to delete these entries, then:
  composer dump-autoload && php bin/console cache:clear

$ bin/console oro:entity-config:debug:stale --remove

Found 2 stale entry/entries:
  Acme\Bundle\ShipmentBundle\Entity\Delivery
  Acme\Bundle\ShipmentBundle\Entity\DeliveryItem

Stale entries removed. Re-run cache:clear.

The improved exception message points developers directly to this command, so the workflow
becomes self-documenting.