Magento 2 'Class ... Does Not Exist' Error: Why It Happens and How to Fix It

Class Vendor\Module\Something does not exist is one of the most common errors in Magento development, and one of the most confusing — the class usually does exist, right where you'd expect it. The error is almost never about the file being missing.

Cause 1: Stale Generated Code

Magento compiles interceptors, factories, and proxies into the generated/ directory. If you've added a new class, changed a constructor, or renamed something, the compiled cache can go stale and reference the old definition.

rm -rf generated/code/* generated/metadata/*
bin/magento setup:di:compile
bin/magento cache:flush

This is the fix for probably 70% of "Class does not exist" reports. If you're in developer mode, Magento generates code on the fly, so this is less likely — but it still happens after a git pull that touched DI-related classes.

Cause 2: The Module Isn't Enabled

If the class lives in a module that's disabled (or was never registered), Magento's autoloader won't find it even though the file is sitting right there on disk.

bin/magento module:status Vendor_Module

If it shows as disabled:

bin/magento module:enable Vendor_Module
bin/magento setup:upgrade

Cause 3: Composer Autoload Is Out of Date

If you added a new PHP file and it's not covered by an existing PSR-4 autoload mapping (common with a freshly created module or a non-standard directory structure), regenerate the autoloader:

composer dump-autoload -o

Cause 4: Namespace and Folder Structure Mismatch

Magento (and PSR-4 in general) expects your namespace to exactly mirror your folder path. Vendor\Module\Model\Source\Options must live at Vendor/Module/Model/Source/Options.php — not Options/Options.php, not Source/Option.php. On a case-sensitive filesystem (any real Linux server, including production), a class name that differs from the filename only in casing will fail here even though it works fine on a case-insensitive local filesystem — which is exactly why this error often only shows up after deployment, never locally.

Cause 5: Missing use Statement or Wrong Fully Qualified Name

If the error names a class you don't recognize at all, check whether it's an interface being referenced from a di.xml preference or a constructor type-hint — a typo in a preference node's type attribute produces this exact error, and it's easy to miss since the string isn't validated until Magento tries to actually instantiate it.

<preference for="Vendor\Module\Api\SomethingInterface"
             type="Vendor\Module\Model\Somethign" /> <!-- typo -->

Fastest Path to Diagnosis

Run these three in order — most of the time you won't need to go further than the first one:

rm -rf generated/code/* generated/metadata/*
bin/magento setup:di:compile

bin/magento module:status Vendor_Module

composer dump-autoload -o

If all three come back clean and the error persists, the problem is almost always a typo somewhere in a di.xml type or preference attribute — grep for the exact class name across your etc/ directories rather than assuming the file itself is wrong.