Fix Next.js missing .next/BUILD_ID at server startup

TL;DR#

next start serves a production build; it does not create one. Run next build successfully, then start from the same application directory with the same output-directory configuration. If a build already succeeded elsewhere, verify that its output reached the runtime folder. An existing .next directory or a working development server does not establish that the production artifact is present.

The Stack Overflow report comes from a 2018 Heroku deployment using Next.js 4 and a custom server. Its message was:

Could not find a valid build in the '.next' directory! Try building your app with 'next build' before starting the server.

Current Next.js documents the equivalent missing production build error. The legacy package versions and deployment platform are not a recipe for a current application; the relevant requirement is a completed production build that the running server can locate.

Why it happens#

The Next.js CLI reference separates three operations: development renders through the development server, build creates optimised production output, and start runs the production server using that output. A package script named dev is just a script name; its command and server configuration determine what actually runs.

In the source report, the only application script starts server.js. Its custom server passes a development flag derived from NODE_ENV, so the same command can request production mode after deployment. A successful local development session does not supply the missing production compilation. The current custom-server documentation also treats server setup separately from the application's build.

The tested Next.js 16.4.0 server implementation reads the BUILD_ID file inside the configured output directory. If that file is absent, it throws the production-build error. That gives you a precise diagnostic to check instead of guessing from whether a directory exists.

The ordinary start/build sequence and the controls below were reproduced with Next.js 16.4.0, React 19.2.0 and Node 24.21.0 in an isolated Docker container. The run is logged on 13 October 2026 in UTC. The production builds used Webpack. No Heroku deployment or historical Next.js 4 application was recreated.

Fix#

1. Confirm which command and directory the server uses. Inspect your deployment's start command and the application package scripts. From the application folder, these PowerShell checks show the current directory and package configuration:

   powershell

   Get-Location
   Get-Content -LiteralPath 'package.json'

   Make this check in the runtime environment as well as the build environment. A monorepo root, a release folder and a container work directory can be different application roots. The CLI accepts an explicit directory, but when one is omitted it uses the current directory. In the reproduction, changing only the selected application directory to an unbuilt sibling reproduced the error; selecting the original built application restored the expected page.

2. Provide a real production build step. For a standard application using the Next.js CLI, merge these scripts into the existing package.json rather than replacing its dependencies or other configuration:

   json

   {
     "scripts": {
       "dev": "next dev",
       "build": "next build",
       "start": "next start"
     }
   }

   Then build and start from that application's folder. Stop if the build fails:

   powershell

   npm run build
   if ($LASTEXITCODE -ne 0) { throw 'Production build failed; do not start this release' }
   npm run start

   If the application genuinely needs a custom server, keep its required start command and add the framework build step before launching it in production. Renaming the custom-server script does not compile the application. The CLI scripts above describe the ordinary server tested here, not a replacement for every custom routing setup.

3. Fix the preceding build error rather than the later startup symptom. The build command must finish successfully. Merely starting it, seeing compilation progress or finding files under .next is insufficient. In the controlled test, start failed before the build; running the build without changing source or configuration generated the artifact, and the same start command then served HTTP 200 with the expected fixture page.

   If the build itself now reports Missing Suspense boundary with useSearchParams, use the Suspense build-error fix. If it instead names authOptions as an invalid Route export on an affected Next.js version, see the Route Handler export fix. These address specific earlier failures; repeatedly attempting production startup cannot repair them.

4. Preserve the build output through deployment. When compilation succeeds but startup cannot find its artifact, inspect what the release process actually copied and what is mounted over the application's output directory. Source files alone are not the ordinary production build. Check inside the final runtime folder, not only on the machine that performed compilation:

   powershell

   Test-Path -LiteralPath '.next/BUILD_ID'
   Get-Item -LiteralPath '.next/BUILD_ID'

   The path above is for the default output directory. A false result is useful evidence; a true result is only one necessary check. Do not manufacture a marker file to silence the error. The application also needs the rest of the output produced by the successful build.

Verify the fix#

Check an actual route through the production server and confirm its expected content. In the reproduction, the startup log printed Ready before the missing-build error and process exit. That banner alone was therefore not a reliable success condition for this tested stack.

After a successful build, the test performed an HTTP request, checked status 200 and checked the expected page text. It then stopped that server by its own process ID before running each control. The same verification worked after restoring the correct application directory and after building with the matching custom output configuration.

The file check also had a deliberate negative control: only the original BUILD_ID file was moved aside while every other build file stayed in place. Startup produced the same missing-build message. Restoring that original file, with the rest of the original output unchanged, restored the working route. This isolates the diagnostic check; it does not show that an arbitrary BUILD_ID can turn an incomplete folder into a valid release.

If a Docker build fails earlier with ENOTFOUND for another service name, that is a separate build-time connectivity problem. The Next.js Docker hostname explanation distinguishes a fetch performed during image compilation from one performed inside the running Compose service. Solve that earlier error before expecting an application build to exist.

When distDir points somewhere other than .next#

The output-directory configuration reference documents how to change the default build directory. For example, a project can use this configuration:

const nextConfig = {
  distDir: 'build'
};
 
export default nextConfig;

The production server and compiler must see the same configuration. Changing the folder name at startup does not move a previously generated build into that location. In the test, a valid default .next build existed, then only the configuration changed to select build. Startup failed and named the build directory. Compiling with that same configuration produced build/BUILD_ID, after which the production route worked.

Inspect both environments' configuration and copied files before rebuilding repeatedly. If the deployment package omits the configuration used during compilation, or runs from another application root, its selected output can differ from the artifact you checked locally. Follow the directory named in the actual error rather than assuming every application uses the default path.

Development files are not a production release#

The current CLI documentation places development output under .next/dev. That layout was verified on the tested Next.js 16.4.0 fixture: the development server returned the expected page and created development artifacts, but no production BUILD_ID appeared at the default production path. After the development process stopped, next start still failed. This version-specific directory layout is not being attributed to the old Next.js 4 report.

Use the development command when developing locally and the completed production output when deploying the ordinary production server. If the application works in development, that tells you its development path can run; it does not establish that a release build completed, reached the right runtime folder or matches the server's configuration. Keep those three checks explicit, then verify a real production request before treating the deployment as fixed.

Further reading: Fix Vercel 'Git author must have access to the project'. Also see Fix: sh: 1: next: not found on Heroku, Fix Next.js Docker: Cannot find module '/app/server.js', Fix: Cannot set property Request of #<Object> getter. Also see Fix Vercel 404: NOT_FOUND Deploying an Express App. Also see Fix Export encountered errors on following paths in Next.js.