Class not found 🐘 PHP

PHP Fatal error: Uncaught Error: Class "X" not found

PHP couldn’t load the class — autoloading failed, the namespace is wrong, or the dependency isn’t installed.

Seen on: PHP

Meaning

Modern PHP relies on Composer’s PSR-4 autoloader. The class name (with namespace) must map to a file path that exists with matching case.

Common causes

  • vendor/ missing — composer install not run on server
  • Namespace/use statement wrong
  • File name or directory case differs from class (works on macOS, fails on Linux)
  • Autoload map stale after adding classes
  • Missing PHP extension providing the class (e.g. PDO, ZipArchive)

⚡ Quick fix

  1. Run composer install (and composer dump-autoload)
  2. Check use statements and namespace declarations
  3. Match file name case to class name exactly
  4. Enable the extension for built-in classes

Detailed fix by platform

PHP

  1. composer dump-autoload -o after adding classes; verify autoload.psr-4 in composer.json maps the namespace prefix to the right folder.

Code examples

PSR-4 mapping must match folders and case

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

With this mapping, App\Services\Mailer must live in src/Services/Mailer.php — exact case on Linux. Run composer dump-autoload after changes.

Missing use statement

php
namespace App\Http\Controllers;

use App\Models\Invoice;          // without this line PHP looks for App\Http\Controllers\Invoice

class BillingController {
    public function show(int $id) { return Invoice::find($id); }
}

How to diagnose

  1. Name — Fully qualified class name correct?
  2. Autoload — Does PSR-4 map it to an existing file?
  3. Deploy — Is vendor/ present on the server?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.