Lumen route:cache failures with closure routes in API deployments

Problem: routes work locally but 404/500 after route:cache in production

In Lumen, running php artisan route:cache for performance can make API endpoints disappear or throw 500 errors in production while they work fine without caching in local development. The useful takeaway is that Lumen cannot serialize closure routes for caching, and stateless API routing is strict about namespaces, autoloading, and middleware registration.

This guide assumes Lumen 8, 9, 10 or 11 where route caching is supported but many Laravel features are disabled by default. Behavior is version sensitive.

Recognizable condition

• After deploy, php artisan route:cache succeeds or fails with a serialization message, and subsequent requests return 404 Not Found or 500 Internal Server Error.
• php artisan route:list shows fewer routes after caching than before.
• Error logs mention unable to serialize closure, target class does not exist, or class not found for a controller that exists locally.
• The issue appears only with caching enabled; php artisan route:clear restores routes.

Cause diagnostic table

Cause	Typical symptom	Quick check
Closure based route	500 on first request after cache, route missing from route:list	Search routes/api.php and routes/web.php for Route::get(..., function)
API route in web.php with session middleware	404 for stateless clients, missing routes after cache	Verify route file and middleware group
Controller namespace / PSR-4 mismatch	Target class not found / 500	Compare class namespace to composer.json autoload and file path
Custom middleware not registered	Silent route drop or 500	Check app/Http/Kernel.php $routeMiddleware and provider registration

Ordered checks

1. Confirm framework version and cache support

Run at project root. Requires read access to composer.json.

cat composer.json | grep lumen/framework

Note the major version. Route cache exists in Lumen 5.7+ but closure incompatibility persists across versions.

2. Compare route list before and after cache

Run from project root with artisan executable permissions.

php artisan route:list > /tmp/routes_before.txt
php artisan route:cache
php artisan route:list > /tmp/routes_after.txt

Risk: route:cache writes bootstrap/cache/routes.php. Clear it before testing changes.

Check if count and names differ. Missing routes point to serialization or autoload problems.

3. Inspect route definitions for closures

Open routes/api.php and routes/web.php. Look for inline closures.

grep -n "function(" routes/api.php

Lumen cannot cache closures. They must be replaced with controller actions.

4. Verify controller existence and namespace

For a failing route like App\Http\Controllers\UserController@index:

• Confirm file exists under app/Http/Controllers/UserController.php
• Confirm namespace declaration matches composer.json PSR-4 mapping for "App\\"

Run at project root:

composer dump-autoload

This regenerates autoload files. Required after moving or renaming classes.

5. Confirm middleware registration and stateless grouping

Check app/Http/Kernel.php for middleware registration. Lumen disables sessions by default; using session middleware on API routes causes unexpected drops.

API routes should be in routes/api.php and use the stateless middleware group.

Fixes tied to findings

Replace closure routes with controllers

If closures are found, create a controller method and point the route to it.

// before
Route::get('/ping', function () { return response()->json(['ok'=>true]); });

// after
Route::get('/ping', 'App\Http\Controllers\HealthController@ping');

Clear then re-cache:

php artisan route:clear
php artisan route:cache

Verify with route:list that the route is present after caching.

Move API routes to correct file and group

Ensure routes are defined in routes/api.php. Avoid session or web middleware for stateless APIs.

Correct namespace and autoload

Align file path with PSR-4 namespace, then run composer dump-autoload and re-cache. Do not assume discovery works without explicit autoload.

Register custom middleware

Add middleware to app/Http/Kernel.php $routeMiddleware and ensure its service provider is loaded in bootstrap/app.php. Remove session dependent middleware for APIs.

Limitations and verification

Lumen disables Blade, sessions and many providers by default. Behavior differs from full Laravel and changes across major versions.

Practical verification steps:

• Run route:list before and after route:cache to confirm presence.
• Test a minimal controller route after clearing cache to isolate serialization vs autoload issues.
• Check production logs for class not found errors immediately after cache.

Escalation criteria

Escalate when:

• Route cache errors persist after replacing all closures and correcting namespaces.
• Custom service providers fail to load in production only, suggesting environment specific autoload or .env differences.
• 404s occur for routes visible in route:list, indicating server configuration, opcode cache, or web server routing issues beyond Lumen.

Rollback for route cache changes is php artisan route:clear which removes bootstrap/cache/routes.php and restores runtime route loading.