PHP "Class not found" Error: Autoload, Namespace and Case Fixes

PHP raises this when code names a class (via new, a static call, extends, or ::class usage) that has not been loaded and cannot be autoloaded. PHP 8 quotes the name with double quotes; PHP 7 prints it with single quotes. It's the same error either way.

PHP Fatal error:  Uncaught Error: Class "App\Services\Mailer" not found in /var/www/app/Checkout.php:27

Read the class name exactly, including its namespace. Whether it has a namespace, and whether it looks like a built-in class, tells you which of these causes applies.

Causes, most likely first

1. The Composer autoloader is missing or stale. The vendor/ directory was not deployed, composer install was never run, or you added a class and did not refresh the classmap.
2. Namespace and path do not match. PSR-4 requires the namespace to mirror the directory structure.
3. Filename case. Mailer.php and mailer.php are different on Linux, though they are the same on macOS and Windows. Code that worked locally fails on the server.
4. Missing use statement or a wrong relative namespace.
5. The class belongs to a PHP extension that is not installed, for example ZipArchive, Redis, NumberFormatter, DOMDocument or SimpleXMLElement.
6. A required package is not installed or was removed from composer.json.

Step 1: confirm the autoloader runs

Your entry script must load Composer's autoloader once:

require __DIR__ . '/vendor/autoload.php';

On the server, check that the file exists and rebuild the maps:

ls vendor/autoload.php
composer install --no-dev --optimize-autoloader
composer dump-autoload

If you deploy with composer dump-autoload --classmap-authoritative (or -a), the autoloader will not look at the filesystem at all, so any class missing from the generated map fails. Rerun it after every change, as part of the deploy.

Step 2: match namespace, folder and filename

With this composer.json mapping:

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

the class App\Services\Mailer must live in src/Services/Mailer.php, and that file must declare namespace App\Services; and class Mailer. Check the filename's capitalization character by character. To find mismatches on a case-sensitive system:

find src -iname 'mailer.php'
grep -rn "^namespace" src/Services/Mailer.php

Changing the PSR-4 map in composer.json requires composer dump-autoload to take effect.

Step 3: check use statements and relative names

Inside a namespace, an unqualified class name resolves against the current namespace, not the global one. Calling new DateTime() inside namespace App; looks for App\DateTime. Fix it with a leading backslash (new \DateTime()) or use DateTime;. The error shows the namespaced name, which exposes this at once.

Step 4: built-in or extension classes

If the class is a standard one and the name has no namespace, an extension is probably missing. Verify with the CLI and with the web SAPI (they can differ):

php -m | grep -i -E "zip|redis|intl|dom|xml"
sudo apt install php8.2-zip php8.2-intl php8.2-xml
sudo systemctl restart php8.2-fpm

See also call to undefined function, which has the same extension story for functions.

Step 5: no Composer, hand-written includes

Without Composer you need an autoloader of your own, or require_once before use:

spl_autoload_register(function (string $class): void {
    $file = __DIR__ . '/src/' . str_replace('\\', '/', $class) . '.php';
    if (is_file($file)) {
        require $file;
    }
});

WordPress and framework notes

In WordPress plugins, a "Class not found" right after an update often means a half-uploaded vendor/ folder or a dependency plugin that is now deactivated. Reinstall the plugin and see WordPress critical error on this website. In Laravel, run composer dump-autoload and php artisan optimize:clear after changing class locations.

Verify

Load the failing page again and check the response with the HTTP Status Checker. From the command line, a one-line test proves the autoloader works: php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\\Services\\Mailer'));" should print bool(true).

Next steps

• Compare with Call to a member function on null.
• Read Fix 500 Internal Server Error.
• Check PHP parse errors if the class file itself is broken.
• Keep a watch on the page with an uptime monitor.

FAQ

Why does it work locally but not on the server?

Usually filename case, because Linux is case-sensitive, or a deploy that skipped vendor/ or the regenerated autoloader.

Does composer dump-autoload download anything?

No. It only rebuilds the autoload files from what is already installed. Use composer install to fetch missing packages.

Why does PHP 8 show double quotes around the name?

The message format changed from single to double quotes in PHP 8. Search logs for both forms.

Can OPcache cause this?

Rarely. A stale cache can serve an old file, so reload PHP-FPM after deploys if the error persists after the files are correct.

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.