PHP "Class not found" - Autoloader Out of Date, Run composer dump-autoload in CI

Composer generates an autoloader that maps class names to files. When a new class is added, a namespace changes, or a classmap-optimized autoloader is stale, PHP cannot resolve the class even though the file is on disk - so it throws "Class not found".

What this error means

CI fails with "Class X not found" for a class whose file clearly exists in the repo. The class is new or recently moved, or the build used an optimized/classmap autoloader generated before the change.

PHP Fatal error:  Uncaught Error: Class "App\Service\NewExporter" not found in
/app/src/Console/ExportCommand.php:19
# the file src/Service/NewExporter.php exists but is not in the autoload map

Common causes

The autoloader was not regenerated after adding/moving a class

An optimized classmap (--optimize-autoloader / --classmap-authoritative) is a snapshot. A class added after it was generated is not in the map, so it is unresolvable.

The namespace does not match the PSR-4 prefix or file path

PSR-4 resolves by namespace prefix to directory. A mismatch between the declared namespace, the autoload map, and the file path means the class is never found.

How to fix it

Regenerate the autoloader

Rebuild the class map so new and moved classes are included.

composer dump-autoload --optimize
# in CI, ensure install runs after checkout so the map is fresh

Verify the PSR-4 mapping matches the file

1. Confirm the class namespace matches an autoload.psr-4 prefix in composer.json.
2. Confirm the file path under that prefix matches the class name exactly (case-sensitive on Linux CI).
3. Run composer dump-autoload again and confirm the class now resolves.

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

Avoid authoritative classmaps during active development

--classmap-authoritative makes Composer refuse to scan the filesystem for unmapped classes. Use it for production artifacts, not for jobs that add classes after install.

How to prevent it

• Run composer install/dump-autoload after checkout so the autoloader matches the tree.
• Keep namespaces aligned with PSR-4 prefixes and exact (case-sensitive) file paths.
• Reserve authoritative/optimized classmaps for built artifacts, not dev/test jobs.

Related guides