Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

My Express server deployed to Vercel answers 404 on every route

Error404: NOT_FOUND

Short answer

Vercel only finds an Express app when a file named app, index or server sits in a supported spot and exports the app or calls listen. Static files must live in public, because express.static is ignored. If the file layout is right, check that the URL belongs to a live deployment.

  • Applies to Express 5, Node.js 22, Vercel
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the failed request in the deployment's runtime logs, then list where your entry file really is. Vercel looks for one of a fixed set of file names.

    ls app.* index.* server.* src/app.* src/index.* src/server.* 2>/dev/null
    grep -n "require('express')\|from 'express'" app.* index.* server.* src/*.* 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1Every route returns 404: NOT_FOUND, including a plain GET /The entry file is not where Vercel looksFix
    2. 2The file name is right, the build passes, but routes still return 404The app is neither exported nor listeningFix
    3. 3API routes work, but index.html, images and CSS return 404Static files are served with express.staticFix
    4. 4Even a freshly created hello-world project gives NOT_FOUND on this URLThe URL points at a deployment that is gone or unreachableFix

What does the error look like?

  • 404: NOT_FOUND
  • The page works with node index.js but not on the .vercel.app URL
  • Images, CSS or index.html served by express.static return 404

Cause 1 of 4

The entry file is not where Vercel looks

1Check

Vercel detects an Express app from a file that imports express and is named app, index or server (extensions js, cjs, mjs, ts, cts, mts), either in the project root or in src. A file called main.js, or one inside a folder like backend/, is not picked up.

ls

2Fix

Rename or move the entry file to one of the supported names and locations, for example src/index.js or server.js.

git mv backend/main.js src/index.js
git commit -am "Move Express entry to src/index.js"

3Verify

Redeploy and request the root route.

vercel deploy
curl -i https://your-project.vercel.app/

Confirmed by vercel.com

Did this fix it?

Cause 2 of 4

The app is neither exported nor listening

1Check

The file must export the app as the default export, or start a port listener with app.listen. A file that builds the app and does nothing else gives Vercel nothing to run.

tail -n 5 src/index.js

2Fix

Export the app. With CommonJS use module.exports, with ES modules use export default.

// CommonJS (package.json has no "type": "module")
const express = require('express');
const app = express();
app.get('/', (req, res) => res.json({ ok: true }));
module.exports = app;

3Verify

Redeploy and call a route you defined.

curl -i https://your-project.vercel.app/

Confirmed by vercel.com

Did this fix it?

Cause 3 of 4

Static files are served with express.static

1Check

On Vercel, express.static() is ignored. Static assets are served by the CDN from the public directory.

grep -rn "express.static" .
ls public

2Fix

Move the files into public/ at the project root and remove the express.static line.

mkdir -p public
git mv static/* public/

3Verify

Redeploy and request a file by its path, without the public prefix.

curl -I https://your-project.vercel.app/logo.png

Confirmed by vercel.com

Did this fix it?

Cause 4 of 4

The URL points at a deployment that is gone or unreachable

1Check

Vercel lists a typo in the URL, a deleted deployment, an unavailable deployment and missing permissions as the reasons for this error.

# Dashboard: Project > Deployments, confirm the deployment exists and is Ready

2Fix

Open the URL shown on the project's Deployments page, read that deployment's logs, and make sure your account can view the project.

# Dashboard: open the deployment, read its logs, and check Team Members and Roles for your access

3Verify

The deployment is Ready and the URL loads.

curl -I https://your-project.vercel.app/

Confirmed by vercel.com

Did this fix it?

How do I stop it coming back?

  • Start from the official template with vc init express, then move your routes in.
  • Keep one entry file named index, app or server so detection never has to guess.
  • Put every static asset in public/ from day one.
  • Run vercel dev before pushing, so a missing export shows up on your machine.

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

Web apps

The cors-anywhere.herokuapp.com demo proxy stopped working

Missing required request header. Must specify one of: origin,x-requested-with

The public cors-anywhere.herokuapp.com server is only a demo, is rate limited, and since February 2021 requires an opt-in.

2 causes, each with a fix

Web apps

CORS fails when you open an HTML file straight from disk

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///

A page opened from disk has an opaque origin, so browsers treat every request it makes as cross-origin, and CORS only works over http or https.

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.