Fatal Error: Uncaught Error: Class Not Found

Why it happens

• The class is defined in another plugin that is switched off, was deleted, or has not loaded yet. An add-on that needs a main plugin breaks when the main plugin is off.
• The plugin uses Composer and its vendor/ folder is incomplete. It was left out of the zip, half uploaded, or built before a class was added, so the autoloader has no path for the name.
• The file name and the class name differ in capital letters. Client.php saved as client.php loads on a Mac or Windows laptop and fails on a Linux server.
• The code uses a WordPress admin class such as WP_List_Table before WordPress has loaded it. WordPress loads that class only inside the admin, and only after plugins have loaded.
• A namespace slip. Inside a namespaced file, new Exception() means Acme\Tools\Exception, which does not exist. The message then shows a name you never wrote.

How to fix it

Try the fixes in this order. Each one is independent: stop as soon as the error is gone.

PHP was asked to create an object from a class it does not know. It looked in its list of loaded classes, asked every autoloader, and found nothing, so it stopped the request. The class name in the message tells you which of five problems you have, and each has a short fix. The quickest way to get the site back is to turn off the plugin named in the file path.

What you see#

Depending on the server settings, you see one of two things. If PHP shows its errors on the page, the message appears at the top, as in the picture. If it does not, the visitor sees "There has been a critical error on this website" and the message is only in wp-content/debug.log. See the critical error page for that screen.

The log line is the same text with a timestamp, and it names the file and the line:

PHP Fatal error:  Uncaught Error: Class "Acme_Shop\Cart" not found in /var/www/html/wp-content/plugins/acme-addon/acme-addon.php:6

With debug display off, the same request returned status 500. With display on, it returned status 200, because PHP had already begun to send the page. That is why a monitor that only checks the status code can miss it.

How PHP finds a class#

PHP does not read every file when a request starts. A class is defined when its file runs. When code says new Client() and no class of that name is defined, PHP calls the autoloaders registered with spl_autoload_register(). Each one gets the full class name and may load a file. The PHP manual says autoloaders are "a last chance to load the class or interface before it fails with an error." If none defines it, PHP throws the Error you see.

WordPress core has no autoloader for its own classes. Core loads them with require. That matters for admin classes. In WordPress 7.1, wp-settings.php includes every active plugin first and fires plugins_loaded afterwards. WP_List_Table is required from wp-admin/includes/admin.php, which wp-admin/admin.php loads, and only then does admin_init fire.

Composer plugins add an autoloader of their own. A plugin's vendor/autoload.php registers one that turns Acme\Orders\Client into the path src/Client.php. If that file is not loaded, or its map has no entry, break A or B happens.

Class names are not case sensitive in PHP, so new wp_error() works. File names on Linux are case sensitive, so the file the autoloader opens must match exactly. That is break C.

Which cause matches the message#

I made each of these on a WordPress 7.1.4 test site with PHP 8.3 and read the real log line.

A renamed file and a missing src/ folder give the same line, so the log cannot tell them apart. Look in the folder. The names Acme_Shop, Acme\Orders and Acme\Tools are from my test plugins; yours will differ.

Cause 1: the main plugin is not there#

An add-on that uses a class from another plugin fails whenever the other plugin is off. The log line above is this case. WordPress keeps the active plugins in alphabetical order. I activated the shop first and the add-on second, and the saved list was still acme-addon then acme-shop. So the add-on's file is read before the shop's, even when both are active. Code that runs at load time can fail for that reason alone. Code that runs on plugins_loaded or later, as in my test, only fails when the other plugin is really missing.

I activated the add-on alone and the front end returned 500. After wp plugin activate acme-shop acme-addon, it returned 200.

Cause 2: the vendor folder#

Plugins that use Composer ship a vendor/ folder. Three things go wrong with it:

• The folder is not there. If the plugin requires vendor/autoload.php without checking, PHP stops earlier with a different message:

PHP Warning:  require_once(/var/www/html/wp-content/plugins/acme-orders/vendor/autoload.php): Failed to open stream: No such file or directory in /var/www/html/wp-content/plugins/acme-orders/acme-orders.php on line 5PHP Fatal error:  Uncaught Error: Failed opening required '/var/www/html/wp-content/plugins/acme-orders/vendor/autoload.php' (include_path='.:/usr/local/lib/php') in /var/www/html/wp-content/plugins/acme-orders/acme-orders.php:5

• The plugin checks with file_exists() first and goes on without it. Then the first new on a Composer class gives this page's message instead.
• The folder is there but old. With the optimized, authoritative class map, I added src/Mailer.php and left the map as it was. Composer had been told that a class missing from the map does not exist, so it did not look in src/:

PHP Fatal error:  Uncaught Error: Class "Acme\Orders\Mailer" not found in /var/www/html/wp-content/plugins/acme-orders/acme-orders.php:8

After composer dump-autoload --classmap-authoritative, the same request returned 200.

composer install --no-dev --optimize-autoloader

Installing dependencies from lock fileNothing to install, update or removeGenerating optimized autoload files

Cause 3: the file name differs in capitals#

On the test site I renamed src/Client.php to src/client.php. The class is still Client, PHP does not mind capitals in class names, and the autoloader asked the Linux file system for src/Client.php. It was not there:

PHP Fatal error:  Uncaught Error: Class "Acme\Orders\Client" not found in /var/www/html/wp-content/plugins/acme-orders/acme-orders.php:8

Renaming the file back gave 200. This is the usual reason a plugin "works on my laptop" and fails after a move to a host.

Cause 4: an admin class used too early#

This is the common one in custom plugins. A class that extends WP_List_Table is defined when its file is included. I asked a request what was loaded at each moment, with a small test plugin:

A request to admin-ajax.php with no action stops early with status 400 and never reaches admin_init. With an action, the class is there at admin_init but still not at plugins_loaded. So even inside the admin, a plugin that extends WP_List_Table at the top of its file fails. On the test site, a plugin with class Orders_Table extends WP_List_Table returned 500 on the front page and on its own admin page. The log said Class "WP_List_Table" not found.

One trap: the same plugin activated without a complaint. WP-CLI loads the admin files before it activates a plugin, so wp plugin activate table-early printed "Success: Activated 1 of 1 plugins." The next normal request failed. I tested this with WP-CLI. Do not take a successful activation as proof that the code is safe.

Cause 5: a namespace slip#

A file that starts with namespace Acme\Tools; looks up every class name inside its own namespace first. new Exception( 'x' ) therefore asks for Acme\Tools\Exception:

PHP Fatal error:  Uncaught Error: Class "Acme\Tools\Exception" not found in /var/www/html/wp-content/plugins/ns-plugin/ns-plugin.php:7

The name in the message is not one the author typed. If you see your own namespace in front of a PHP or WordPress class, add the backslash.

A plugin that fails when you switch it on#

When a plugin has the error at the top level of its file, WordPress refuses to activate it. With WP-CLI, wp plugin activate plain-missing printed the fatal error and a stack trace, and afterwards the plugin was not in the active list, so the site kept working. See plugin could not be activated because it triggered a fatal error for the browser screen. Errors inside a hook, such as init or plugins_loaded, are only found when the hook runs, so those plugins activate and then break the site.

If you change a file and nothing happens#

PHP's opcode cache checks files for changes on a timer. On the test image the timer is 2 seconds. When I changed a file and loaded the page in the same second, I saw the old result. Wait a few seconds before you decide a fix did not work.

After the fix#

Load the page, then read wp-content/debug.log for new lines. Turn WP_DEBUG off when you are done. Before you update the plugin that caused this, read how to update plugins safely. A different message, "Call to undefined function", has its own causes: see uncaught error: call to undefined function. If PHP says a function is declared twice, see cannot redeclare function.