Maaz Zindani

Loading the index…

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

A Next.js build succeeds on Vercel, then the deploy cannot find routes-manifest.json

Error"routes-manifest.json" couldn't be found

Short answer

Vercel looks for the build output in the folder it expects, and routes-manifest.json is in it. When the error appears, Vercel is looking in the wrong place or the folder was never produced. Check the Output Directory and Build Command overrides, the Root Directory, then monorepo cache outputs.

  • Applies to Next.js 15, Vercel project settings, Turborepo 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the same build locally and look at what folder it creates. That folder is what Vercel must be pointed at.

    npx next build && ls .next/routes-manifest.json
  2. 2Match what you see, then jump to its fix

    1. 1Project Settings shows an Output Directory override, or vercel.json has outputDirectory.Output Directory is overridden to something Next.js does not build intoFix
    2. 2The build log ends quickly and no .next folder is listed.The Build Command is overridden and does not run next buildFix
    3. 3The repository has the Next.js app in a subfolder such as apps/web.The Root Directory points at the repository root, not the appFix
    4. 4The error appears only on cached builds, and a redeploy without the build cache works.Turborepo or Nx does not cache the Next.js outputFix

What does the error look like?

  • "routes-manifest.json" couldn't be found
  • No Output Directory

Cause 1 of 4

Output Directory is overridden to something Next.js does not build into

1Check

For Next.js, Vercel sets the output directory by itself. next.config only changes it when you set distDir.

grep -n "distDir" next.config.*
cat vercel.json 2>/dev/null | grep -n outputDirectory

2Fix

Turn the Output Directory override off in Project Settings under Build and Deployment, and remove outputDirectory from vercel.json. If you really use a distDir, make both agree.

// next.config.js (only if you need a custom folder)
module.exports = {
  distDir: 'build',
}

3Verify

Redeploy; the build log passes the output step.

npx vercel --prod

Confirmed by vercel.com

Did this fix it?

Cause 2 of 4

The Build Command is overridden and does not run next build

1Check

For Next.js Vercel runs the build script from package.json, or next build when there is none. An override can replace it with something that does not build.

grep -n '"build"' package.json

2Fix

Turn the Build Command override off, or set it to the real build command.

{
  "scripts": { "build": "next build" }
}

3Verify

The deployment log shows the Next.js route table at the end of the build.

npx next build

Confirmed by vercel.com

Did this fix it?

Cause 3 of 4

The Root Directory points at the repository root, not the app

1Check

In a repository where the app lives in a subfolder, Vercel needs that folder as the project Root Directory.

ls apps/web/package.json apps/web/next.config.* 2>/dev/null

2Fix

Open Project Settings, Build and Deployment, Root Directory, and enter the app folder (for example apps/web).

# Project Settings > Build and Deployment > Root Directory: apps/web

3Verify

Redeploy, then confirm the build log starts in that folder.

npx vercel --prod

Confirmed by vercel.com

Did this fix it?

Cause 4 of 4

Turborepo or Nx does not cache the Next.js output

1Check

Vercel's guide says the error shows when the correct directories are not cached between builds. Redeploy without the cache to test this.

cat turbo.json

2Fix

Declare the Next.js output in the build task so it is restored from the cache.

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

3Verify

Deploy twice in a row; the second, cached build also passes.

npx turbo run build

Confirmed by vercel.com

Did this fix it?

How do I stop it coming back?

  • Leave Build Command and Output Directory on the framework default unless you have a reason.
  • Set the Root Directory once when you import a monorepo, and write it into your setup notes.
  • Keep distDir out of next.config unless something requires it.

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.