← ./articles

Next.js routes-manifest.json Missing? Check for Parallel next build First

nextjsbuilddebuggingciagentsstatic-export

routes-manifest.json missing errors in Next.js usually send people toward configuration problems: the wrong Vercel root directory, a bad cache, a monorepo output path, or a static export setting.

Those causes are real. But there is another failure mode that is easy to miss: two next build processes writing to the same .next/ directory at the same time.

If you use AI coding agents, parallel CI jobs, local task runners, or multiple terminals, this is worth checking before you rewrite configuration.

The symptom

The error usually looks like a missing manifest inside .next/:

Cannot find module '<project>/.next/routes-manifest.json'

or:

The file ".next/routes-manifest.json" couldn't be found.

Because the missing file lives under .next/, it is natural to assume the build did not produce the right output. That can be true. But if the failure appears during page-data collection, static generation, or export finalization, and another build was running at the same time, the manifest may have been deleted or half-written by the other process.

Why parallel builds corrupt .next/

next build owns the .next/ directory. During a build, Next.js writes manifests, traced output, server files, static pages, and cache data into that directory.

If two build processes share the same project folder, they also share the same .next/ folder:

build A -> writes .next/
build B -> writes .next/

The race looks like this:

  1. Build A starts and prepares .next/
  2. Build B starts and also prepares .next/
  3. One build is writing routes-manifest.json
  4. The other build reads or replaces the same area
  5. One process sees a missing, stale, or incomplete manifest

The result is an error that looks like a Next.js configuration issue, even though the root cause is shared artifact corruption.

Why this is easy to misdiagnose

Search results for routes-manifest.json couldn't be found mostly point to deployment configuration, monorepo output directories, cache problems, or missing build output. Those are good checks, especially on Vercel.

But they do not cover every local or agent-driven workflow.

In an AI-agent workflow, for example, two agents may be given separate implementation tasks. If both agents finish by running npm run build, they can race on the same .next/ directory. One build may pass while the other fails with a missing manifest.

The misleading part is that the failing build can report a framework-looking error. The actual bug is orchestration: two writers touched the same generated directory.

How to confirm the cause

Before changing Next.js config, answer these questions:

  • Was another next build running in the same project folder?
  • Did two agents, terminals, CI steps, or npm scripts run build at the same time?
  • Did the failure disappear after running one clean build by itself?
  • Does deleting .next/ and out/, then running a single build, fix it?
  • Are there no code changes between a failed parallel build and a successful single build?

On Windows PowerShell, a clean local check can be:

Remove-Item -Recurse .next, out -ErrorAction SilentlyContinue
npm run build

Use the equivalent safe removal command for your shell. The important point is not the exact command; it is that only one build process owns the artifact directory.

The fix: serialize the build

The practical fix is to make one process responsible for the final build.

In an agent workflow:

agent A: edit source files only
agent B: edit source files only
orchestrator: run one final npm run build

Do not let every parallel worker run npm run build in the same checkout.

In CI:

job A: lint/typecheck
job B: unit tests
job C: build

If multiple jobs truly need to build, isolate them:

  • separate checkout directories
  • separate worktrees
  • separate build artifact directories
  • separate CI workspaces

The rule is simple: parallel source checks are fine; parallel writes to the same build output are not.

Worktree isolation for advanced cases

If each agent or CI job must run a build, give each one a separate working tree:

git worktree add ../build-a --detach
git worktree add ../build-b --detach

Each worktree gets its own .next/ directory. That removes the shared artifact race.

After the independent work is done, merge or apply the source changes back and run one final authoritative build in the main workspace.

Do not confuse this with static export issues

There is another routes-manifest.json-adjacent problem in Next.js static export: metadata routes such as robots.ts, sitemap.ts, or RSS route handlers may need to be forced static.

That is a configuration problem. Parallel .next/ corruption is an orchestration problem.

If your build fails every time, even when only one build is running, look at static export settings, route handlers, monorepo output paths, and deployment platform configuration.

If your build fails only when multiple builds overlap, serialize or isolate the builds first.

For static export-specific issues, see 5 Pitfalls of Next.js output: export and How to Avoid Them.

Checklist

When you see a missing .next/routes-manifest.json error:

  • Check whether another next build is running
  • Stop parallel builds in the same project folder
  • Delete generated output (.next/, and out/ if using static export)
  • Run one clean npm run build
  • If the clean build passes, fix the workflow, not the Next.js config
  • If the clean build still fails, move on to config, monorepo, route, or cache diagnosis

This order prevents a common detour: changing application code to fix a build-artifact race.

Summary

A missing routes-manifest.json does not always mean your Next.js config is wrong.

If two next build processes write to the same .next/ directory, they can corrupt each other's generated artifacts. The fix is to serialize the final build or isolate each build in its own workspace.

Before debugging framework settings, check the boring process question: was more than one build writing to .next/?

References