Maaz Zindani

Loading the index…

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

routes/api.php is missing in a new Laravel project

ErrorUnable to locate the api.php route file

Short answer

A new Laravel 11 or newer project ships without routes/api.php. API routing is opt-in: run php artisan install:api, which creates the file and installs Sanctum. If the file exists but its routes return 404, the api argument is missing from withRouting() in bootstrap/app.php.

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

Fix it fast

  1. 1Find out which cause you have

    Check whether the file exists and whether bootstrap/app.php loads it.

    ls routes/
    grep -n "api" bootstrap/app.php
  2. 2Match what you see, then jump to its fix

    1. 1The routes folder has web.php and console.php only.API routing was never installedFix
    2. 2routes/api.php is present (for example after an upgrade from Laravel 10), yet its URLs give 404 and route:list does not show them.The file exists but bootstrap/app.php does not load itFix

What does the error look like?

  • Unable to locate the api.php route file
  • There is no routes/api.php in the project
  • An existing api.php route returns 404 under /api

Cause 1 of 2

API routing was never installed

1Check

The Laravel docs say a stateless API is enabled with the install:api Artisan command. Until you run it, no api.php file exists.

ls routes/

2Fix

Run the command. It installs Laravel Sanctum and creates routes/api.php with a sample /user route.

php artisan install:api

3Verify

The file exists and the route list shows it under the api prefix.

ls routes/api.php
php artisan route:list | grep api

Confirmed by laravel.com

Did this fix it?

Cause 2 of 2

The file exists but bootstrap/app.php does not load it

1Check

Routes are loaded by the withRouting call in bootstrap/app.php. By default it lists web, commands and health only. The api route file is registered when you add the api argument.

sed -n 1,25p bootstrap/app.php

2Fix

Add the api argument next to web. The /api prefix is applied for you, and apiPrefix changes it.

->withRouting(
    web: __DIR__.'/../routes/web.php',
    api: __DIR__.'/../routes/api.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
)

3Verify

Clear any cached routes, then list the routes again.

php artisan route:clear
php artisan route:list | grep api

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • After creating a project that needs a JSON API, run install:api once and commit routes/api.php and the Sanctum migration.
  • Do not paste a Laravel 10 bootstrap or RouteServiceProvider into a newer app; routes are registered in bootstrap/app.php now.

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.