PHP Class not found — Class does not exist or autoloader cannot locate it
Fatal error: Class not found / not found in ...
Verified against PHP 8.3 documentation, Composer autoloading documentation, PSR-4 autoloader standard · Updated June 2026
> quick_fix
Run `composer dump-autoload` to regenerate the class map, then verify that the namespace in the class file matches the `use` statement and the directory structure follows PSR-4 conventions.
<?php
// Ensure autoloader is included
require_once __DIR__ . '/vendor/autoload.php';
// Correct PSR-4 use statement
use App\Services\PaymentService;
$service = new PaymentService();
// Check if class exists before instantiation
if (!class_exists(PaymentService::class)) {
throw new RuntimeException('PaymentService class not found — check autoload');
}
// CLI: regenerate autoload
// composer dump-autoloadWhat causes this error
PHP throws a fatal 'Class not found' error (PHP 7: 'Fatal error: Class not found', PHP 8: may appear as 'Cannot find class') when it cannot locate a class definition. Causes include: Composer autoload not regenerated after adding a new class, wrong namespace in the class file, missing `use` statement in the calling file, or the Composer vendor/autoload.php file not being included.
How to fix it
- 01
step 1
Run composer dump-autoload
The first fix to try: `composer dump-autoload` in your project root. This regenerates vendor/composer/autoload_classmap.php. Any new class files added since the last dump will not be in the map. Run it after adding or moving any PHP class file.
- 02
step 2
Verify the namespace matches the directory structure
PSR-4: if your composer.json maps `"App\\" : "src/"`, then the class `App\Services\PaymentService` must be in `src/Services/PaymentService.php`. The namespace in the file must also be `namespace App\Services;`. A mismatch causes class-not-found even after dump-autoload.
- 03
step 3
Add or fix the use statement
In the calling file, verify the `use` statement: `use App\Services\PaymentService;` — not `use Services\PaymentService;`. The fully-qualified class name must match exactly including casing on case-sensitive filesystems (Linux servers).
- 04
step 4
Confirm vendor/autoload.php is required
Check that your entry script (index.php, bootstrap.php) includes `require_once __DIR__ . '/vendor/autoload.php';`. Without this line, no Composer autoloading works and every class will be 'not found'.
- 05
step 5
Check for case-sensitivity on Linux servers
macOS and Windows file systems are case-insensitive; Linux is case-sensitive. A class file named `paymentservice.php` will load on macOS but fail on a Linux server where `PaymentService.php` is required. Ensure file names match the class name exactly.
How to verify the fix
- Run `composer dump-autoload` and then re-run the script — the error should not recur
- Verify with `var_dump(class_exists('App\\Services\\PaymentService'))` — should output bool(true)
- Check the file actually exists at the expected PSR-4 path: `ls src/Services/PaymentService.php`
Why Class not found happens at the runtime level
PHP does not have a native module system. Class resolution at runtime relies entirely on the autoloader registered via spl_autoload_register(). Composer registers a PSR-4/classmap autoloader that translates a class name like App\Services\PaymentService into a file path. When the autoloader cannot find the file — because the class map is stale, the namespace does not match the directory structure, or the autoloader file itself was not included — PHP triggers a fatal 'Class not found' error that halts execution.
Common debug mistakes for Class not found
- Adding a new class file without running `composer dump-autoload` — the class map is stale
- Namespace in the PHP file does not match the directory structure (e.g., `namespace Services;` instead of `namespace App\Services;`)
- File name case mismatch between macOS development and Linux production
- Forgetting `require_once __DIR__ . '/vendor/autoload.php'` in a standalone script outside the framework entry point
When Class not found signals a deeper problem
The Class not found error in PHP is a direct consequence of the language's non-native module resolution. PSR-4 brought discipline to this via Composer, but it requires correct alignment between namespace, directory path, and file name — three separate things that must stay in sync. In large teams, class files moved or renamed without updating the namespace cause this error only in production (Linux) not locally (macOS), creating a category of bugs that CI/CD on Linux catches but local development does not.
Editor's take
Fatal error: Class not found is PHP telling you it can't locate a class definition at the moment you try to instantiate or reference it. In modern PHP with Composer autoloading, this almost always means one of three things: the class file exists but the namespace declaration doesn't match the PSR-4 directory structure, `composer dump-autoload` hasn't been run after adding or moving files, or the case sensitivity of the filename doesn't match the class name (Linux filesystems are case-sensitive, macOS isn't by default — a notorious deployment trap). In Laravel, this error is especially common after creating a model or controller manually instead of using `php artisan make:model`, because artisan handles the namespace and directory placement correctly. Another frequent production cause: an interface or abstract class is referenced in a type hint but the package that provides it was listed in `require-dev` instead of `require`, so it's not installed on the production server. For WordPress plugins, this error usually means you're calling a class from another plugin that hasn't been loaded yet — WordPress doesn't guarantee plugin load order. The diagnostic approach: check `composer show` to verify the package is installed, verify the file exists at the expected PSR-4 path, confirm the namespace in the file matches exactly, and run `composer dump-autoload -o` for the optimized classmap. Understanding PHP's autoloading chain is essential for debugging this class of error.
By Bikram Nath · Curator · Updated June 2026
Frequently asked questions
Why does my class work locally but not in production?
Linux servers are case-sensitive; macOS is not. If your file is `paymentService.php` but the class is `PaymentService`, it works on macOS but fails on Linux. Also check that you ran `composer install --no-dev` in production and the vendor directory was committed or installed on the server.
What is the difference between class_exists() and interface_exists()?
class_exists('Foo') checks for classes and abstract classes. interface_exists('Foo') checks for interfaces. trait_exists('Foo') checks for traits. Using class_exists() on an interface returns false. Use the correct function for the type you are checking.
Why does adding a class to an existing namespace not work after composer dump-autoload?
Check your composer.json autoload section. If you use 'classmap' autoloading rather than 'psr-4', the class map file must be regenerated. If using psr-4, confirm the directory path in composer.json points to the parent directory and the namespace prefix is correct.