Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Laravel cannot find your controller: Target class does not exist

ErrorIlluminate\Contracts\Container\BindingResolutionException: Target class [UserController] does not exist.

Short answer

Laravel 8 stopped adding the App\Http\Controllers prefix to controller names in route files. A route written as 'UserController@index' now looks for a class with no namespace and fails. Write the route with the class constant, or a full class name, or restore the namespace property in RouteServiceProvider. Clear a stale route cache afterwards.

  • Applies to Laravel 8 to 12, PHP 8.3, PHP 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print what the router actually has for that route. The Action column shows the class string Laravel will try to build.

    php artisan route:list --path=users
  2. 2Match what you see, then jump to its fix

    1. 1Target class [UserController] does not exist, and the name has no App\Http\Controllers in front of itThe route uses the old string syntax without a namespaceFix
    2. 2Dozens of routes use the string syntax and rewriting them is not possible todayYou want the old automatic prefix back across a large route fileFix
    3. 3You fixed the route file, but the same error appears, or only on the server after a deployA cached route list still holds the old definitionsFix

What does the error look like?

  • Illuminate\Contracts\Container\BindingResolutionException: Target class [UserController] does not exist.
  • ReflectionException: Class App\Http\Controllers\UserController does not exist

Cause 1 of 3

The route uses the old string syntax without a namespace

1Check

Open the route file and look at how the controller is written. A bare 'UserController@index' string used to be completed with a default namespace. Since Laravel 8 the RouteServiceProvider property that supplied it is null in new projects, so nothing completes the name.

grep -n "@" routes/web.php routes/api.php
grep -n "namespace" app/Providers/RouteServiceProvider.php

2Fix

Import the controller and pass it as a class and method pair. This also lets your editor jump to the class.

use App\Http\Controllers\UserController;

// before
Route::get('/users', 'UserController@index');

// after
Route::get('/users', [UserController::class, 'index']);

3Verify

The Action column now shows the full class name, and the page loads.

php artisan route:list --path=users
curl -I http://localhost:8000/users

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

You want the old automatic prefix back across a large route file

1Check

The upgrade guide describes the escape hatch: give RouteServiceProvider a namespace and apply it when the route files are loaded. This only exists in applications that still have a RouteServiceProvider with a routes() callback; Laravel 11 and newer no longer ship that file.

sed -n '1,60p' app/Providers/RouteServiceProvider.php

2Fix

Set the property and attach it to each group in boot().

protected $namespace = 'App\\Http\\Controllers';

public function boot()
{
    $this->routes(function () {
        Route::middleware('web')
            ->namespace($this->namespace)
            ->group(base_path('routes/web.php'));

        Route::prefix('api')
            ->middleware('api')
            ->namespace($this->namespace)
            ->group(base_path('routes/api.php'));
    });
}

3Verify

Clear caches and open a route that used the string syntax.

php artisan route:clear
php artisan route:list --path=users

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

A cached route list still holds the old definitions

1Check

When routes are cached, Laravel loads the cache and ignores the route files. If route:cache ran before your edit, the old controller string is still what runs.

ls bootstrap/cache/routes*.php

2Fix

Delete the cache, and rebuild it as part of the deploy only after the code is in place.

php artisan route:clear
# on production, after deploying the new code:
php artisan route:cache

3Verify

Request the route again.

php artisan route:list --path=users

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Write every controller route with the [Controller::class, 'method'] form, so a typo becomes an editor warning instead of a runtime error.
  • Run php artisan route:list in CI to catch a broken route before deploy.
  • Run route:cache only as the last step of a deploy, never before the new code is copied.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.