fix: improve error when starting next without building

[flotwig]

Addresses #57066

Currently, a user running next start on an un-built Next.js project receives a confusing uncaught error before the process just ends:

   ▲ Next.js 14.1.0
   - Local:        http://localhost:3000

[Error: ENOENT: no such file or directory, open '/home/flotwig/src/project/.next/BUILD_ID'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/home/flotwig/src/project/.next/BUILD_ID'
}

In my case, I ran into this because I had not worked with Next.js for a while, and I forgot that next dev was used for local development, not next start. I believe many of the confused users in #57066 are making a similar mistake and not realizing it, due to the error message.

This PR catches an ENOENT when reading BUILD_ID and suggests that the user next build or next dev to remove this friction point:

   ▲ Next.js 14.1.1-canary.69
   - Local:        http://localhost:3000

Error: Could not find a production build in the '.next' directory. Try building your app with 'next build' before starting the production server. https://nextjs.org/docs/messages/production-start-no-build-id
    at setupFsCheck (/home/flotwig/src/next.js/packages/next/src/server/lib/router-utils/filesystem.ts:157:13)
    at initialize (/home/flotwig/src/next.js/packages/next/src/server/lib/router-server.ts:90:21)
    at Server.<anonymous> (/home/flotwig/src/next.js/packages/next/src/server/lib/start-server.ts:295:28)

A few things probably need to be resolved before this PR can merge, I would appreciate any input from Next.js maintainers.

• Is this the best place to catch this? I am not familiar with the Next.js codebase, so I just caught this in the most obvious way.
• Can the error message be improved?
• Add a test for the error in test/development

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: 007f519

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[ijjk]

See above comment

[flotwig]

@ijjk Thanks for taking a look. I updated the error message as suggested and added an e2e test in 8684cf1, please have another look when you have time.

[ijjk]

Stats from current PR

Default Build

General Overall increase ⚠️

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
buildDuration	13.8s	13.8s	N/A
buildDurationCached	7.4s	6.3s	N/A
nodeModulesSize	197 MB	197 MB	⚠️ +2.07 kB
nextStartRea..uration (ms)	426ms	425ms	N/A

Client Bundles (main, webpack)

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
2453-HASH.js gzip	30.5 kB	30.5 kB	N/A
3304.HASH.js gzip	181 B	181 B	✓
3f784ff6-HASH.js gzip	53.7 kB	53.7 kB	N/A
8299-HASH.js gzip	5.04 kB	5.04 kB	N/A
framework-HASH.js gzip	45.2 kB	45.2 kB	✓
main-app-HASH.js gzip	242 B	242 B	✓
main-HASH.js gzip	32.1 kB	32.2 kB	N/A
webpack-HASH.js gzip	1.7 kB	1.7 kB	N/A
Overall change	45.6 kB	45.6 kB	✓

Legacy Client Bundles (polyfills)

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
polyfills-HASH.js gzip	31 kB	31 kB	✓
Overall change	31 kB	31 kB	✓

Client Pages

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
_app-HASH.js gzip	196 B	197 B	N/A
_error-HASH.js gzip	184 B	184 B	✓
amp-HASH.js gzip	505 B	505 B	✓
css-HASH.js gzip	324 B	325 B	N/A
dynamic-HASH.js gzip	2.5 kB	2.5 kB	N/A
edge-ssr-HASH.js gzip	258 B	258 B	✓
head-HASH.js gzip	352 B	352 B	✓
hooks-HASH.js gzip	370 B	371 B	N/A
image-HASH.js gzip	4.2 kB	4.2 kB	✓
index-HASH.js gzip	259 B	259 B	✓
link-HASH.js gzip	2.67 kB	2.67 kB	N/A
routerDirect..HASH.js gzip	314 B	312 B	N/A
script-HASH.js gzip	386 B	386 B	✓
withRouter-HASH.js gzip	309 B	309 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Overall change	6.56 kB	6.56 kB	✓

Client Build Manifests

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
_buildManifest.js gzip	483 B	485 B	N/A
Overall change	0 B	0 B	✓

Rendered Page Sizes

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
index.html gzip	527 B	527 B	✓
link.html gzip	540 B	540 B	✓
withRouter.html gzip	523 B	522 B	N/A
Overall change	1.07 kB	1.07 kB	✓

Edge SSR bundle Size

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
edge-ssr.js gzip	95 kB	95 kB	N/A
page.js gzip	3.05 kB	3.06 kB	N/A
Overall change	0 B	0 B	✓

Middleware size

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
middleware-b..fest.js gzip	625 B	623 B	N/A
middleware-r..fest.js gzip	151 B	151 B	✓
middleware.js gzip	25.5 kB	25.5 kB	N/A
edge-runtime..pack.js gzip	839 B	839 B	✓
Overall change	990 B	990 B	✓

Next Runtimes

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
app-page-exp...dev.js gzip	171 kB	171 kB	✓
app-page-exp..prod.js gzip	96.7 kB	96.7 kB	✓
app-page-tur..prod.js gzip	98.5 kB	98.5 kB	✓
app-page-tur..prod.js gzip	92.9 kB	92.9 kB	✓
app-page.run...dev.js gzip	150 kB	150 kB	✓
app-page.run..prod.js gzip	91.4 kB	91.4 kB	✓
app-route-ex...dev.js gzip	21.3 kB	21.3 kB	✓
app-route-ex..prod.js gzip	15 kB	15 kB	✓
app-route-tu..prod.js gzip	15 kB	15 kB	✓
app-route-tu..prod.js gzip	14.8 kB	14.8 kB	✓
app-route.ru...dev.js gzip	20.9 kB	20.9 kB	✓
app-route.ru..prod.js gzip	14.8 kB	14.8 kB	✓
pages-api-tu..prod.js gzip	9.51 kB	9.51 kB	✓
pages-api.ru...dev.js gzip	9.79 kB	9.79 kB	✓
pages-api.ru..prod.js gzip	9.51 kB	9.51 kB	✓
pages-turbo...prod.js gzip	22.3 kB	22.3 kB	✓
pages.runtim...dev.js gzip	23 kB	23 kB	✓
pages.runtim..prod.js gzip	22.3 kB	22.3 kB	✓
server.runti..prod.js gzip	50.6 kB	50.6 kB	✓
Overall change	950 kB	950 kB	✓

build cache

	vercel/next.js canary	flotwig/next.js better-build-id-error	Change
0.pack gzip	1.56 MB	1.56 MB	N/A
index.pack gzip	105 kB	105 kB	N/A
Overall change	0 B	0 B	✓

Diff details

Diff for middleware.js

Diff too large to display

Commit: 482e12e

[ijjk]

Tests Passed