Fatal error: Uncaught Error: Class 'App\Models\X' not found
ID: php/composer-autoload-class-not-found
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 83 | active | — | — | — |
Root Cause
This fatal error occurs when PHP cannot locate a class that exists in the codebase because Composer's autoload map is stale. It is the single most frequent error AI coding agents produce when scaffolding new classes, models, or services: the agent creates the file with the correct namespace but does not regenerate the autoloader. Other causes include PSR-4 namespace-to-directory mismatches and case sensitivity issues on Linux filesystems.
genericWorkarounds
-
94% success Run 'composer dump-autoload' to regenerate the class map after adding new files
After creating a new class file, run 'composer dump-autoload' (or 'composer dump-autoload -o' for optimized classmap). This scans all PSR-4 and classmap directories defined in composer.json and rebuilds vendor/composer/autoload_*.php files. For AI agents: always run this command after creating or moving any PHP class file. In Laravel, 'php artisan clear-compiled' followed by 'composer dump-autoload' ensures both framework and composer caches are refreshed.
-
92% success Verify the namespace declaration matches the PSR-4 directory mapping in composer.json
Open composer.json and check the 'autoload.psr-4' section. For example, if it maps 'App\\' to 'app/', then a class with namespace App\Models must be in app/Models/ClassName.php. Verify: 1) The namespace in the PHP file exactly matches the directory path relative to the mapped root. 2) The class name exactly matches the filename (case-sensitive on Linux). 3) There are no typos in the namespace separators. Example composer.json entry: {"autoload": {"psr-4": {"App\\": "app/"}}}. After fixing any mismatch, run 'composer dump-autoload'. -
89% success Check file and directory name casing matches the namespace exactly on Linux
Linux filesystems are case-sensitive, so App\Models\UserProfile requires the file path app/Models/UserProfile.php with exact capitalization. Common mistakes: 'app/models/' (lowercase m), 'UserProfile.PHP' (uppercase extension), or 'Userprofile.php' (lowercase p). Use 'ls -la app/Models/' to verify actual filenames on disk. If the file was created on macOS or Windows and pushed to a Linux server, the casing from the original OS may not match. Rename with 'git mv' to preserve history: 'git mv app/models/Userprofile.php app/Models/UserProfile.php'.
Dead Ends
Common approaches that don't work:
-
Adding require_once or include statements to manually load the class file
80% fail
Manual requires bypass the PSR-4 autoloading standard that frameworks like Laravel and Symfony depend on. Other parts of the codebase that expect the class to be autoloadable will still fail. This creates fragile path dependencies and breaks when the file is moved or the project structure changes. It also prevents the class from being discovered by service containers and dependency injection.
-
Deleting the entire vendor/ directory and running composer install from scratch
65% fail
A full vendor reinstall takes significant time (often minutes) and does not address the root cause. If the autoload mapping in composer.json is misconfigured or the namespace does not match the directory structure, a fresh install regenerates the same broken autoload map. This is a shotgun approach when a targeted 'composer dump-autoload' is almost always sufficient.
-
Editing vendor/composer/autoload_classmap.php or autoload_psr4.php manually
90% fail
Files under vendor/composer/ are auto-generated and will be overwritten by the next composer install, update, or dump-autoload. Manual edits to generated files are lost immediately and never address the actual misconfiguration in composer.json. This also risks introducing syntax errors in the autoloader that crash the entire application.