Composer Autoload: Class Not Found After Install/Update

Error summary

Composer finished, but the class still does not resolve—usually PSR-4 path/case mismatch, autoload not dumped, or the web SAPI is not using the `vendor` tree you just built.

What it means

Composer finished, but the class still does not resolve—usually PSR-4 path/case mismatch, autoload not dumped, or the web SAPI is not using the vendor tree you just built.

What the error means

The Composer-generated autoloader cannot map the FQCN to a file that defines the class.

Why PHP produces it

Composer maps namespaces to directories. If the file path, class name, or composer.json autoload section disagree—especially on case-sensitive Linux—the class never loads.

PHP version notes

Optimized autoloaders (-o/-a) can make missing classes fail differently if classmaps are stale—redeploy autoload files with code.

Most common causes

• Namespace does not match folder structure
• Forgot composer dump-autoload
• Deployed code without vendor/ or with stale autoload files
• Case mismatch (UserRepository.php vs userrepository.php)

Minimal examples

BAD — reproduces the problem

{\n  \"autoload\": {\"psr-4\": {\"App\\\\\": \"app/\"}}\n}\n// but class lives in src/Repository/UserRepository.php

FIXED — safer pattern

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

Step-by-step diagnosis

1. Confirm class file path vs PSR-4 prefix.
2. Inspect vendor/composer/autoload_psr4.php for the prefix.
3. Run composer dump-autoload -v and watch which paths are registered.
4. Ensure the web root uses the same project directory.

Fixes

Fix #1: Dump autoload after structural changes

Regenerate autoload maps in the environment that serves the app.

composer dump-autoload -o

Fix #2: Correct PSR-4 and class path

Make directory + class + namespace agree exactly.

// src/Repository/UserRepository.php\nnamespace App\\Repository;\nclass UserRepository {}

Common mistakes when fixing it

• Running Composer as a different user so vendor/ permissions break web reads

How to prevent it

• Automate composer install --no-dev -o in deploy
• Add a post-deploy smoke request that loads key classes

Web server / environment notes

CI vs production path differences are common

Tags: composer,cli,fpm,linux,docker

Categories

• Classes & Objects
• Composer
• Namespaces & Autoload

Related PHP errors

• Class not found Fatal error: Uncaught Error: Class "%s" not found in %s:%d
• Class not found after Composer install Class "%s" not found
• Composer lock file is not up to date The lock file is not up to date with the latest changes in composer.json.

Relevant ZendStudio.net tools

• Composer.json Validator Validate composer.json structure and common mistakes without running composer install.
• Composer Platform Checker Paste composer.json to list PHP constraints and ext-* platform requirements without running Compose…
• PHP Error Matcher Paste a full PHP error, warning, SQLSTATE, or cURL message to find the best ZendStudio.net troubles…
• PSR-4 Autoload Checker Check whether class paths match composer.json PSR-4 namespace prefixes.