Laravel

Fixing 'Target class [Controller] does not exist' (BindingResolutionException) in Laravel


You register a new route in routes/web.php or routes/api.php, open the endpoint in your browser or run php artisan route:list, and Laravel crashes with an Illuminate\Contracts\Container\BindingResolutionException:

Illuminate\Contracts\Container\BindingResolutionException

Target class [UserController] does not exist.

Or, when the namespace is partially resolved:

Illuminate\Contracts\Container\BindingResolutionException

Target class [App\Http\Controllers\Api\UserController] does not exist.

This error happens when Laravel’s IoC (Inversion of Control) Service Container attempts to instantiate your controller using PHP’s ReflectionClass, and Composer’s PSR-4 autoloader cannot locate a matching class definition on disk.


Quick Diagnostic Reference

Match the exact class string inside the error brackets [...] to find the root cause:

Error Signature / Scenario Underlying Cause Jump to Fix
Target class [UserController] does not exist (No App\... prefix) Missing use import or using removed Laravel 7 'Controller@method' syntax Fix 1
Works on Windows / macOS, fails on Linux VPS or Docker container Filename capitalization does not match the PHP class name (PSR-4 violation) Fix 2
Target class [App\Http\Controllers\Api\...] fails even with use statement Controller file is inside a subfolder, but its namespace line omits the subfolder Fix 3
Class and namespace are 100% valid, or controller was recently moved Stale Composer classmap or locked bootstrap/cache/routes-v7.php file Fix 4
Target class [auth.admin] or custom middleware alias fails in Laravel 11/12 Middleware alias was not registered inside bootstrap/app.php Fix 5

1. Modern Route Syntax & Missing use Imports

Prior to Laravel 8, RouteServiceProvider automatically prepended the App\Http\Controllers namespace to every string-based controller route. In modern Laravel (8, 9, 10, 11, and 12), that automatic namespace prefix is removed.

If you write 'UserController@index' without importing the class, Laravel looks for a global \UserController class in the root namespace and throws Target class [UserController] does not exist.

The Fix: Use Array Tuple Syntax with Explicit Imports

Open routes/web.php (or routes/api.php), import the controller at the top of the file, and pass [Controller::class, 'method']:

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\UserController; // <-- 1. Import the full namespace

// ❌ BROKEN: Unprefixed legacy string syntax
Route::get('/users', 'UserController@index');

// ✅ WORKING: Modern array syntax
Route::get('/users', [UserController::class, 'index']);

// ✅ WORKING: Single-action invokable controller (__invoke)
Route::post('/users/export', UserController::class);

IDE Auto-Import Trap: When typing UserController::class inside VS Code or PhpStorm, make sure your editor did not accidentally auto-import the wrong class at the top of your route file (such as use App\Models\User as UserController; or use Illuminate\Routing\Controller;).


2. The Windows/macOS to Linux & Docker Case-Sensitivity Trap

One of the most frustrating variations of this bug occurs when your routes work on your local Windows or macOS machine, but throw Target class [App\Http\Controllers\BookingController] does not exist the moment you deploy to an Ubuntu VPS or run inside a Docker container.

Why this happens:

  • Windows (NTFS) and macOS (APFS) are case-insensitive by default. If your file is named bookingController.php or Bookingcontroller.php, Windows loads BookingController without complaining.
  • Linux (ext4 / xfs inside Ubuntu & Docker) is strictly case-sensitive. Composer’s PSR-4 autoloader maps App\Http\Controllers\BookingController directly to the exact file path app/Http/Controllers/BookingController.php. If a single letter’s casing differs, Linux reports that the file does not exist.

How to fix it in Git:

Because Git often ignores case-only filename changes on Windows and macOS, simply renaming the file in your IDE sidebar may not register in git status. Use git mv with -f to force Git to track the exact capitalization:

# Rename a lowercase file to strict PascalCase in Git
git mv -f app/Http/Controllers/bookingController.php app/Http/Controllers/BookingController.php

# Commit and push the case correction
git commit -m "fix: correct PSR-4 controller filename casing for Linux"
git push origin main

3. Subfolder Namespace Mismatches (Controllers/Api/ or Controllers/Admin/)

When organizing controllers into subdirectories—such as app/Http/Controllers/Api/V1/OrderController.php—three things must match identically:

  1. The physical folder path: app/Http/Controllers/Api/V1/OrderController.php
  2. The namespace declaration inside the controller: namespace App\Http\Controllers\Api\V1;
  3. The use statement in your route file: use App\Http\Controllers\Api\V1\OrderController;

A common mistake when moving a controller from app/Http/Controllers/ into app/Http/Controllers/Api/ is forgetting to update the namespace line at the top of the controller file:

<?php

// ❌ BROKEN when file is located at app/Http/Controllers/Api/OrderController.php:
namespace App\Http\Controllers;

// ✅ WORKING: Namespace must mirror the exact directory tree under app/
namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // ...
    }
}

(Note: When moving controllers into an Api namespace for a decoupled React or Vue frontend, ensure your stateless API routes are placed in routes/api.php rather than routes/web.php so they aren’t blocked by web session CSRF checks. See our guide on Fixing Laravel 419 Page Expired (CSRF Token Mismatch) and Fixing Laravel CORS Preflight Errors).


4. Rebuilding Corrupted Composer Autoload Maps & Route Caches

If your file path, class name, and namespace are all completely accurate, Laravel is reading from a stale Composer classmap or a cached route manifest.

Run these two commands in your terminal to rebuild the autoloader and flush all framework caches:

# 1. Regenerate Composer's PSR-4 autoload map
composer dump-autoload -o

# 2. Clear cached routes, config, and compiled container services
php artisan optimize:clear

Checking composer.json PSR-4 Mappings

If composer dump-autoload still does not register classes inside app/, open composer.json and verify that the autoload.psr-4 block maps App\\ to app/ with a capital A:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    }
},

(Warning: When running composer dump-autoload or php artisan optimize:clear on a Linux production server, always execute the command under your deployment user rather than root so you don’t lock out PHP-FPM from storage/ and bootstrap/cache/. See Fixing storage/logs/laravel.log Permission Denied in Linux & Docker for the safe ownership setup).


5. The Middleware Alias Trap in Laravel 11 & 12 (Target class [admin] does not exist)

Sometimes the error message does not name a controller at all—instead, it names a short string like [role], [admin], or [check.tenant]:

Target class [admin] does not exist.

Why this happens:

You attached a middleware alias to a route (->middleware('admin')), but that alias has not been registered. When Laravel cannot find a matching middleware alias, it falls back to asking the Service Container to instantiate a PHP class literally named admin, which fails immediately.

In Laravel 10 and older, middleware aliases lived in app/Http/Kernel.php. In Laravel 11 and 12, Kernel.php no longer exists.

How to register middleware aliases in Laravel 11 & 12:

Open bootstrap/app.php and register your alias inside the withMiddleware closure:

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use App\Http\Middleware\EnsureUserIsAdmin;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'admin' => EnsureUserIsAdmin::class,
        ]);
    })
    ->withExceptions(function ($exceptions) {
        //
    })->create();

Verification: Audit All Registered Routes at Once

You do not need to click through every page in your browser to see if another route has a broken controller binding. Run Artisan’s route inspection command with the -v (verbose) flag:

php artisan route:list -v

When php artisan route:list executes, Laravel resolves and reflects every controller class registered across your application. If the command prints your full route table cleanly without throwing a BindingResolutionException, every controller and middleware class in your project is properly autoloaded.

(If your backend routes resolve cleanly in the terminal, but loading the page in the browser throws a 500 error complaining about public/build/manifest.json, check our guide on Fixing ‘Vite manifest not found’ in Laravel & Docker).