"Class XXX is not a valid entity or mapped super class" after moving the class in the filesystem

"Class XXX is not a valid entity or mapped super class" after moving the class in the filesystem

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The Doctrine Cache Problem After Moving Entity Classes

When you move a PHP class in your filesystem, it's tempting to assume that any tooling relying on that class will automatically pick up the new location. This is rarely true for object-relational mapping (ORM) tools like Doctrine. Specifically, when you attempt to run php app/console doctrine:generate:form after renaming a namespace, you might encounter the error: "Class [OldNamespace]User is not a valid entity or mapped super class."

In the scenario described, an entity originally located at Aib\PlatformBundle\Entity\User was successfully processed by Doctrine. However, after moving the file and updating the namespace to Aib\PlatformBundle\Entity\Identity\User, the command failed immediately. The error message explicitly references the old fully qualified name (Aib\PlatformBundle\Entity\User), indicating that Doctrine is looking for the class at its previous location rather than scanning your current filesystem or autoloader for the updated entity.

This behavior stems from how Symfony and Doctrine handle application caching. When you run a console command, Symfony loads the application kernel, which initializes the Doctrine ORM. During this initialization, Doctrine scans your doctrine.yml (or legacy orm.yml) configuration to build an internal metadata cache. This cache maps entity names and their corresponding file paths. Once cached, Doctrine does not automatically re-scan your app/Entities directory on every command execution unless explicitly told to do so.

Consequently, when the console command attempts to generate a form for Aib:User, it queries its internal metadata store. The store still contains a reference to the old path (Aib\PlatformBundle\Entity\User) because that was the state of the application during the last successful initialization. Since the file no longer exists at that path and the new namespace hasn't been registered in the cache, Doctrine throws the "not a valid entity" exception.

To resolve this, you must clear the application cache to force Doctrine to re-read your configuration and re-scan the entity directory. The specific command for Symfony 2.0.4 is:

php app/console cache:clear --env=prod
# or
php app/console cache:clear --env=test

The --env flag ensures you are clearing the cache relevant to your current environment. In some cases, simply running cache:clear without arguments might suffice if you are in a development environment where the default is dev. Once the cache is cleared, Doctrine will re-initialize the EntityManager and scan for entities based on their actual file locations and namespaces. Running doctrine:generate:form again should then succeed.

Another potential pitfall involves the Doctrine ORM configuration itself. If you are using a custom entity manager or have explicitly defined an entity in your YAML configuration (e.g., under metadata_cache_driver or specific entity mappings), moving the file without updating that configuration can also cause issues. However, in standard Symfony 2 setups with automatic scanning enabled (auto_mapping: true in legacy config or default behavior in newer versions), clearing the cache is usually the fix.

It is also worth noting that changing namespaces requires ensuring your autoloader (Composer) has picked up the changes. While Composer typically handles this automatically after a change, running composer dump-autoload guarantees that the class map is updated if you are experiencing issues beyond just Doctrine caching.

If you prefer not to clear caches frequently in a development workflow, consider using tools like doctrine:migrations:diff or other ORM utilities that respect entity changes more dynamically. However, for form generation tasks, explicitly clearing the cache remains the most reliable solution to align Doctrine's internal state with your actual filesystem structure.

Our network