🚨 Laravel Tip: Fixing “POST Content Too Large” & Mastering Exception Handling in Laravel 11 & 12

🔥 “Ever got hit by the PostContent Too Large error while uploading large files in Laravel? You’re not alone — and more importantly, here’s how to fix it the right way.” 👨‍💻 Real Developer Problem, Real Developer Solution Recently, while working on a Laravel project that allows users to upload files, I ran into a […]

🔥 “Ever got hit by the PostContent Too Large error while uploading large files in Laravel? You’re not alone — and more importantly, here’s how to fix it the right way.”

👨‍💻 Real Developer Problem, Real Developer Solution

Recently, while working on a Laravel project that allows users to upload files, I ran into a classic issue:
POST Content Too Large error.

If you're a Laravel developer handling file uploads through POST requests, chances are you’ve bumped into this error too. It's caused by the server rejecting a request that exceeds the post_max_size limit defined in your server configuration (e.g., php.ini, .htaccess, or nginx/apache settings).

But here’s where things get more Laravel-specific 👇

📌 The Laravel Middleware Behind It: ValidatePostSize

Laravel includes a global middleware named:

\Illuminate\Http\Middleware\ValidatePostSize::class

This middleware checks the size of the incoming POST request and throws an error before the request reaches your controller or route logic. This means you can't catch this error using regular exception handling methods inside your controller or even your global Handler.php file easily.

🧠 The Real Trick: Reordering Middleware in Laravel 11 & 12

Laravel 11 and 12 have revamped middleware management. Unlike previous versions where you simply modified Kernel.php, now you need to work with the middleware in bootstrap/app.php using the new removeFromGroup(), prepend(), and priority() methods.

To show custom error messages using session flash (for web routes) or JSON responses (for API), the StartSession middleware needs to run before ValidatePostSize.

Here’s how to do it right:

// bootstrap/app.php

use Illuminate\Session\Middleware\StartSession;
use Illuminate\View\Middleware\ShareErrorsFromSession;

$middleware->removeFromGroup('web', [
    StartSession::class,
    ShareErrorsFromSession::class,
]);

$middleware->prepend([
    StartSession::class,
    ShareErrorsFromSession::class,
]);

$middleware->priority([
    \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
    \Illuminate\Http\Middleware\TrustHosts::class,
    \Illuminate\Http\Middleware\TrustProxies::class,
    \Illuminate\Http\Middleware\HandleCors::class,
    \Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class,
    StartSession::class,
    ShareErrorsFromSession::class,
    \Illuminate\Http\Middleware\ValidatePostSize::class,
    \Illuminate\Foundation\Http\Middleware\TrimStrings::class,
    \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
]);

👉 This ensures that session flash messages are available when ValidatePostSize triggers and gives you control over how errors are displayed.

💡 Bonus Tip: Handle API Errors Gracefully

If you're building APIs with route-model binding, and a resource isn’t found, Laravel throws a NotFoundHttpException. By default, Laravel will dump a technical error log — which is not helpful (and sometimes risky!) to return to mobile apps or frontend clients.

Here's how to override it with a clean and friendly JSON response:

// app/Exceptions/Handler.php

use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

$exceptions->renderable(function (NotFoundHttpException $e, $request) {
    if ($request->wantsJson()) {
        return response()->json([
            'success' => false,
            'message' => 'Oops! Request is invalid or the requested data is not available.',
            'data' => []
        ], 404);
    }
});

✅ Best Practices You Should Always Follow

1. Always set proper post_max_size and upload_max_filesize in your PHP settings.
2. Handle server-side limitations through Laravel middleware.
3. Flash error messages through sessions only if session middleware is available before validation middleware.
4. Use JSON responses with clear error messages for APIs.
5. Never expose internal paths, stack traces, or sensitive info in production.

🚀 Wrapping Up

Modern Laravel (v11 and v12) gives you fine-grained control over how middleware executes — but with power comes complexity.

By carefully reordering your middleware, handling exceptions smartly, and customizing your error responses, you’ll create a much more resilient, user-friendly, and secure application — whether it's web or API.