How to Fix the 'Class Not Found' Error in PHP

"Class not found" is one of the most common PHP errors, and also one of the most misdiagnosed — the fix depends entirely on why PHP can't find the class, and there are more causes than "just run composer dump-autoload."

Cause 1: Composer's Autoloader Is Stale

If you added a new class recently, Composer's generated autoload files may not know about it yet:

composer dump-autoload

This works immediately for PSR-4-mapped classes in most cases, since PSR-4 resolves by folder convention. It's required, not optional, for classmap-based autoloading, since that map is a static generated snapshot with no runtime fallback.

Cause 2: Missing or Wrong use Statement

A class in a different namespace needs an explicit use import, or a fully-qualified name. This is the single most common cause in day-to-day work:

// Fails: Uuid is not in the global namespace
$id = Uuid::uuid4();

// Works
use Ramsey\Uuid\Uuid;
$id = Uuid::uuid4();

Modern IDEs (PhpStorm, VS Code with Intelephense) auto-import on autocomplete, which is exactly why this error is more common when writing code by hand or copy-pasting a snippet from elsewhere without its imports.

Cause 3: Namespace Doesn't Match Directory Structure (PSR-4)

PSR-4 autoloading is purely structural — the namespace must mirror the folder path exactly, relative to the mapped base directory in composer.json:

{
    "autoload": { "psr-4": { "App\\": "app/" } }
}

Under this mapping, App\Services\Mailer must live at exactly app/Services/Mailer.php. A typo in either the namespace declaration at the top of the file or the actual folder name (case matters on Linux, even though it may silently work on case-insensitive Windows/macOS filesystems) breaks resolution.

Cause 4: The File Was Never Required by Anything

If a class lives outside any autoload-mapped directory (a one-off script, an old file not covered by psr-4 or classmap), no autoloader will ever find it. Either move it into a mapped directory or add it explicitly:

{
    "autoload": { "classmap": ["legacy/one-off-scripts"] }
}

...followed by another composer dump-autoload to actually pick up the new mapping.

Cause 5: Case Sensitivity Between Environments

Windows and macOS filesystems are case-insensitive by default; Linux (including virtually every production server and CI runner) is not. Code that works locally with use App\Models\user; against a file named User.php will fail with "class not found" the moment it runs on Linux, because the class name genuinely doesn't match the filename there. Fix the casing to match exactly rather than relying on your local OS being forgiving.

Cause 6: Opcache Serving a Stale Cached File List

Rare, but real on production servers with aggressive opcode caching: PHP's opcache can hold on to a compiled version of a file from before a deploy replaced it. Restart PHP-FPM (or clear opcache explicitly via opcache_reset()) after a deploy if a class that clearly exists on disk still isn't found.

A Systematic Way to Diagnose It

1. Read the exact class name in the error — including namespace. A typo there is the fastest thing to rule out.
2. Confirm the file exists at the path PSR-4 would compute for that namespace.
3. Run composer dump-autoload -o and retry.
4. Check vendor/composer/autoload_classmap.php or autoload_psr4.php to see exactly what Composer thinks it knows about.
5. If it works locally but not on a server, suspect case sensitivity or a stale deploy before anything else.

Stuck on a stubborn autoloading or dependency issue? Get in touch — I work as a freelance PHP developer.