Maaz Zindani

Loading the index…

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

Laravel routes return 404 or throw NotFoundHttpException

ErrorSymfony\Component\HttpKernel\Exception\NotFoundHttpException

Short answer

A 404 means Laravel found no route for that URL, or the request never reached Laravel at all. Run php artisan route:list first. If the route is listed, the web server rewrite or the document root is wrong. If it is not listed, look at stale route cache, the /api prefix and the route file that should hold it.

  • Applies to Laravel 12, PHP 8.3, nginx 1.26, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the routes Laravel has registered and look for yours. Whether it appears decides where to look.

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

    1. 1Only / works, or every other URL gives the web server's own 404 page rather than Laravel'sThe web server does not send requests to public/index.phpFix
    2. 2The route is in routes/web.php but missing from route:listThe route cache is out of dateFix
    3. 3route:list shows the URI starting with api/, but you call it without that prefixThe route is in routes/api.php and you forgot the /api prefixFix

What does the error look like?

  • Symfony\Component\HttpKernel\Exception\NotFoundHttpException

Cause 1 of 3

The web server does not send requests to public/index.php

1Check

Laravel's deployment guide requires the document root to be the public folder and every request to fall back to public/index.php. Check the root and the try_files line.

sudo nginx -T | grep -n -E "root|try_files"

2Fix

Point root at the public directory and send unknown paths to index.php, as in the guide's nginx example.

root /srv/example.com/public;
index index.php;

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

3Verify

Test the config, reload nginx and request a route that is not the home page.

sudo nginx -t && sudo systemctl reload nginx
curl -I https://example.com/posts

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

The route cache is out of date

1Check

After route:cache, the cached file is loaded on every request and new routes are not seen until it is rebuilt.

ls bootstrap/cache

2Fix

Clear the cache. Only run route:cache again during a deployment, after the routes are final.

php artisan route:clear
# at deploy time, if you use route caching
php artisan route:cache

3Verify

The route is now listed.

php artisan route:list --path=posts

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

The route is in routes/api.php and you forgot the /api prefix

1Check

Routes in routes/api.php get the /api prefix automatically. In a new Laravel project that file does not exist until you create it with install:api.

ls routes/
php artisan route:list --path=api

2Fix

Call the URL with the prefix, or create the API routing if the file is missing. The prefix can be changed with apiPrefix in bootstrap/app.php.

php artisan install:api

// bootstrap/app.php
->withRouting(
    api: __DIR__.'/../routes/api.php',
    apiPrefix: 'api',
)

3Verify

Call the prefixed URL.

curl -i https://example.com/api/posts

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Run php artisan route:list in CI after a change to the route files.
  • Run route:clear before route:cache in the deploy script.
  • Keep one nginx server block per app, with root set to its public folder.

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

PHP stops the script after 30 seconds

Symfony\Component\ErrorHandler\Error\FatalError: Maximum execution time of 60 seconds exceeded

PHP ends a script that runs past max_execution_time (30 seconds by default for web requests).

5 causes, each with a fix

Back end

Why a Filament panel feels slow on a Laravel server

The panel is fast on a small demo and slow once there are many resources, pages and widgets

A slow Filament panel on a server is most often running without the production caches.

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.