Nextjs output directory error by LukeSheard · Pull Request #14542 · vercel/vercel

LukeSheard · 2026-01-05T18:23:03Z

Add early validation for Next.js output directory and improve error messages to guide users on misconfigurations or empty builds.

The original error message for a missing routes-manifest.json was generic, leading to user confusion when the actual problem was a misconfigured outputDirectory or incorrect Turborepo caching. This PR introduces specific checks for the output directory's existence and content, providing targeted error codes (NEXT_OUTPUT_DIR_MISSING, NEXT_OUTPUT_DIR_EMPTY) and actionable guidance, as well as enhancing the existing NEXT_NO_ROUTES_MANIFEST message.

Linear Issue: CIBA-3001

Co-authored-by: luke.phillips-sheard <luke.phillips-sheard@vercel.com>

cursor · 2026-01-05T18:23:04Z

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

changeset-bot · 2026-01-05T18:23:07Z

🦋 Changeset detected

Latest commit: f50b698

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@vercel/next	Patch
vercel	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-01-05T18:24:14Z

🧪 Test Strategy

Comparing: 1f2a250 → f50b698 (view diff)

Strategy: Affected packages only

✅ Only testing packages that have been modified or depend on modified packages.

Affected packages - 2 (5%)

@vercel/next
vercel

Unaffected packages - 37 (95%)

@vercel-internals/get-package-json
@vercel/backends
@vercel/build-utils
@vercel/cervel
@vercel/cli-auth
@vercel/client
@vercel/config
@vercel/detect-agent
@vercel/edge
@vercel/elysia
@vercel/error-utils
@vercel/express
@vercel/fastify
@vercel/firewall
@vercel/frameworks
@vercel/fs-detectors
@vercel/functions
@vercel/gatsby-plugin-vercel-builder
@vercel/go
@vercel/h3
@vercel/hono
@vercel/hydrogen
@vercel/introspection
@vercel/nestjs
@vercel/node
@vercel/oidc
@vercel/oidc-aws-credentials-provider
@vercel/python
@vercel/redwood
@vercel/related-projects
@vercel/remix-builder
@vercel/routing-utils
@vercel/ruby
@vercel/rust
@vercel/static-build
@vercel/static-config
examples

Results

Unit tests: Only affected packages will run unit tests
E2E tests: Only affected packages will run e2e tests
Type checks: Only affected packages will run type checks

This comment is automatically generated based on the affected testing strategy

vercel

Additional Suggestion:

Line 575 uses relative path for readJSON while rest of code uses absolute paths, causing file not found errors

View Details

📝 Patch Details

diff --git a/packages/next/src/index.ts b/packages/next/src/index.ts
index c42219663..06ef0d663 100644
--- a/packages/next/src/index.ts
+++ b/packages/next/src/index.ts
@@ -573,7 +573,7 @@ export const build: BuildV2 = async buildOptions => {
 
   try {
     const data = await readJSON(
-      path.join(outputDirectory, 'output/config.json')
+      path.join(entryPath, outputDirectory, 'output/config.json')
     );
     buildOutputVersion = data.version;
   } catch (_) {

Analysis

The bug exists at line 575 in packages/next/src/index.ts. The code was using a relative path path.join(outputDirectory, 'output/config.json') for the readJSON call. Since readJSON from fs-extra resolves relative paths from the current working directory (process.cwd()), not from entryPath, the file lookup would fail when the working directory differs from entryPath.

This is inconsistent with:

Line 1290: Uses path.join(entryPath, outputDirectory, 'app-path-routes-manifest.json')
Line 591: Explicitly creates absoluteOutputDirectory = path.join(entryPath, outputDirectory)
All subsequent file operations that use the absolute path

The fix changes line 575 to use path.join(entryPath, outputDirectory, 'output/config.json') to create an absolute path, ensuring the file can be found regardless of the current working directory. This makes the code consistent throughout and prevents silent failures in the buildOutputVersion check.

Use entryPath prefix for build output config.json path to be consistent with the rest of the codebase and ensure the file can be found regardless of the current working directory.

packages/next/src/index.ts

…or-5d0c

marc-vercel

LGTM - There is a comment from Vade that might be correct.

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## vercel@50.2.0 ### Minor Changes - Add `vercel env run` command to run commands with environment variables from the linked Vercel project without writing them to the filesystem ([#14582](#14582)) - Merge computed rewrites/redirects to routes in Vercel config ([#14518](#14518)) ### Patch Changes - Adding in user configured deploymentId to build output type ([#14497](#14497)) - skip secondary installation for vercel.ts ([#14471](#14471)) - Updated dependencies \[[`2eb1b7678bece13e442f8404d519bd07891eb500`](2eb1b76), [`39c95ff6b643a63509571818e67a792df09fd71f`](39c95ff), [`d63084dac296ccb2077ed742bc2ade0264da851d`](d63084d)]: - @vercel/next@4.15.11 - @vercel/build-utils@13.2.5 - @vercel/redwood@2.4.6 - @vercel/rust@1.0.4 - @vercel/static-build@2.8.16 - @vercel/backends@0.0.18 - @vercel/elysia@0.1.16 - @vercel/express@0.1.23 - @vercel/fastify@0.1.19 - @vercel/go@3.3.0 - @vercel/h3@0.1.25 - @vercel/hono@0.2.19 - @vercel/hydrogen@1.3.3 - @vercel/nestjs@0.2.20 - @vercel/node@5.5.17 - @vercel/python@6.1.6 - @vercel/remix-builder@5.5.6 - @vercel/ruby@2.2.4 ## @vercel/build-utils@13.2.5 ### Patch Changes - Adding in user configured deploymentId to build output type ([#14497](#14497)) - skip secondary installation for vercel.ts ([#14471](#14471)) ## @vercel/client@17.2.19 ### Patch Changes - Updated dependencies \[[`e725853a6c41bed634d1e3e2382596f17a18f342`](e725853), [`39c95ff6b643a63509571818e67a792df09fd71f`](39c95ff), [`d63084dac296ccb2077ed742bc2ade0264da851d`](d63084d), [`567d2d41e685cd949274411ce0e60e61a3dc3942`](567d2d4)]: - @vercel/routing-utils@5.3.2 - @vercel/build-utils@13.2.5 ## @vercel/elysia@0.1.16 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.5.17 ## @vercel/express@0.1.23 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.5.17 ## @vercel/fastify@0.1.19 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.5.17 ## @vercel/fs-detectors@5.7.12 ### Patch Changes - Updated dependencies \[[`e725853a6c41bed634d1e3e2382596f17a18f342`](e725853), [`567d2d41e685cd949274411ce0e60e61a3dc3942`](567d2d4)]: - @vercel/routing-utils@5.3.2 - @vercel/frameworks@3.15.4 ## @vercel/gatsby-plugin-vercel-builder@2.0.115 ### Patch Changes - Updated dependencies \[[`39c95ff6b643a63509571818e67a792df09fd71f`](39c95ff), [`d63084dac296ccb2077ed742bc2ade0264da851d`](d63084d)]: - @vercel/build-utils@13.2.5 ## @vercel/h3@0.1.25 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.5.17 ## @vercel/hono@0.2.19 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.5.17 ## @vercel/nestjs@0.2.20 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.5.17 ## @vercel/next@4.15.11 ### Patch Changes - Add early validation for Next.js output directory and improve error messages to guide users when the output directory is missing, empty, or misconfigured. Introduces new error codes `NEXT_OUTPUT_DIR_MISSING` and `NEXT_OUTPUT_DIR_EMPTY` with actionable guidance for common issues like Turborepo cache misconfiguration. ([#14542](#14542)) ## @vercel/node@5.5.17 ### Patch Changes - Updated dependencies \[[`39c95ff6b643a63509571818e67a792df09fd71f`](39c95ff), [`d63084dac296ccb2077ed742bc2ade0264da851d`](d63084d)]: - @vercel/build-utils@13.2.5 ## @vercel/routing-utils@5.3.2 ### Patch Changes - Add respectOriginCacheControl to rewritesSchema ([#14506](#14506)) - Add respectOriginCacheControl to routes schema ([#14565](#14565)) ## @vercel/static-build@2.8.16 ### Patch Changes - Updated dependencies \[]: - @vercel/gatsby-plugin-vercel-builder@2.0.115 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Fix: Improve Next.js output directory error messages

136ea1a

Co-authored-by: luke.phillips-sheard <luke.phillips-sheard@vercel.com>

vercel bot deployed to Preview January 5, 2026 18:23 View deployment

Add changeset for @vercel/next output directory error improvements

d7e898b

vercel bot deployed to Preview January 5, 2026 18:29 View deployment

vercel bot reviewed Jan 5, 2026

View reviewed changes

Fix path for readJSON to use absolute path

0912c9e

Use entryPath prefix for build output config.json path to be consistent with the rest of the codebase and ensure the file can be found regardless of the current working directory.

vercel bot deployed to Preview January 5, 2026 18:35 View deployment

vercel bot reviewed Jan 5, 2026

View reviewed changes

packages/next/src/index.ts Show resolved Hide resolved

Merge branch 'main' into cursor/CIBA-3001-nextjs-output-directory-err…

f50b698

…or-5d0c

vercel bot deployed to Preview January 6, 2026 19:05 View deployment

LukeSheard marked this pull request as ready for review January 6, 2026 23:04

LukeSheard requested review from a team, huozhi, ijjk, timneutkens and ztanner as code owners January 6, 2026 23:04

marc-vercel approved these changes Jan 7, 2026

View reviewed changes

LukeSheard merged commit 2eb1b76 into main Jan 7, 2026
166 checks passed

LukeSheard deleted the cursor/CIBA-3001-nextjs-output-directory-error-5d0c branch January 7, 2026 10:46

vercel-release-bot mentioned this pull request Jan 7, 2026

Version Packages #14551

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Nextjs output directory error#14542

Nextjs output directory error#14542
LukeSheard merged 4 commits intomainfrom
cursor/CIBA-3001-nextjs-output-directory-error-5d0c

LukeSheard commented Jan 5, 2026

Uh oh!

cursor bot commented Jan 5, 2026

Uh oh!

changeset-bot bot commented Jan 5, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 5, 2026 •

edited

Loading

Uh oh!

vercel bot left a comment

Uh oh!

Uh oh!

marc-vercel left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

LukeSheard commented Jan 5, 2026

Uh oh!

cursor bot commented Jan 5, 2026

Uh oh!

changeset-bot bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Test Strategy

Results

Uh oh!

vercel bot left a comment

Choose a reason for hiding this comment

Analysis

Uh oh!

Uh oh!

marc-vercel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot bot commented Jan 5, 2026 •

edited

Loading

github-actions bot commented Jan 5, 2026 •

edited

Loading