Why Your Next.js Build Exploded at 2AM Friday (And How to Fix It)
The deploy log timestamp reads 2:17 AM. Your CI/CD pipeline, which normally finishes npm run build in 90 seconds, has been churning for 22 minutes. The Vercel dashboard shows the build process eating 8GB of RAM. You have a feature demo at 9 AM. Your heart rate spikes.
This is a rite of passage for every solo founder running a Next.js app. The build that worked perfectly yesterday breaks today, and it breaks spectacularly. Here’s the truth: it’s almost never a random cosmic ray. It’s a specific, diagnosable problem. We’ve seen this pattern across hundreds of builds at Trove Deck Solution, and the fix follows a repeatable script.
What Causes a Sudden, Catastrophic Slowdown in a Next.js Build?
The most common cause is an unplanned dependency upgrade that introduces a breaking change or a massive increase in the dependency tree. A silent major version bump in a package like @apollo/client or date-fns can force your build to compile thousands of new modules. According to a 2024 npm Inc. report, the average JavaScript project has 68 direct dependencies, but they pull in a median of 278 transitive dependencies—each a potential build-time bomb.
Your build time is a function of two things: CPU-bound work (compiling, bundling) and I/O-bound work (reading/writing thousands of files). A slowdown points to a sudden, massive increase in one of these.
How to Diagnose the Root Cause: A 5-Step Checklist
Don’t randomly revert commits. Follow this order.
- Check Your
package-lock.jsonDiff First. This is the smoking gun. Rungit diff HEAD~1 package-lock.json. Look for large jumps in transitive dependencies or any package getting a major version update (the first number changes, e.g.,1.2.3to2.0.0). - Isolate the Culprit with a Clean Install. Delete
node_modulesand your lock file (rm -rf node_modules package-lock.json), then runnpm install. If this itself is incredibly slow, your issue is network or package registry-related, not your code. - Profile the Build. Use
NEXT_PROFILE=1 npm run build. This generates aprofile.jsonyou can visualize atnextjs.org/learn/build-profiling. It will show you if time is spent inclientComponents,serverComponents, or juststaticGeneration. - Check for Infinite Static Generation Loops. A common trap: a
getStaticPropsorgenerateStaticParamsfunction that, due to a bad data fetch or logic error, tries to generate millions of pages. Your build log will stall at the “Generating static pages” step. - Inspect Your
next.config.js. Did you recently enablewebpack('experimental')features, a complexrewrites/redirectsrule set, or a powerful but expensive loader like@next/bundle-analyzer? These can have outsized impacts.
The 5 Most Likely Fixes
Once you’ve diagnosed, here’s the fix.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Build hangs at “Compiling client components” | A new dependency has a broken or massive build script. | Identify via lockfile diff. Use npm-force-resolutions or overrides in package.json to pin the old version. |
| “Generating static pages” takes 20+ minutes | getStaticProps is generating too many pages or fetching slowly. |
Add revalidate for ISR, paginate data fetches, or set a hard limit in generateStaticParams. |
| “API Routes” step is slow | A route handler is doing synchronous, blocking work. | Move any heavy computation to a background job. Ensure your API routes are async. |
| Build fails with “JavaScript heap out of memory” | The Node.js process is running out of RAM. | Increase the memory limit: NODE_OPTIONS='--max-old-space-size=4096' npm run build (use 4096 for 4GB). |
| Build is fast locally but slow in CI/CD | The CI environment has weaker hardware (CPU/RAM) or a cold cache. | Configure caching for node_modules and .next/cache in your CI (e.g., GitHub Actions cache). |
# A common fix for memory issues in your CI script
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build
What is the ‘Build Cache’ and Why Did It Fail?
Next.js uses a cache in the .next directory to speed up subsequent builds by only recompiling changed files. In a CI/CD environment like GitHub Actions or Vercel, this cache is typically stored remotely and restored at the start of the build. If the cache is invalidated (e.g., by a lockfile change) or corrupted, you get a full, cold build, which is drastically slower. Always ensure your CI configuration correctly caches the .next/cache folder. We follow a rigorous engineer-led workflow at Trove Deck Solution that includes cache validation as part of our pre-launch QA—because nothing sours a 2AM deployment like a cold cache.
An Overlooked Culprit: Image Optimization
Every <Image> component from next/image can trigger an on-demand optimization during build if the image is missing from the public folder and uses a remote URL. If you added 50 new product images this week, your build might be trying to download and optimize them all. Use the unoptimized prop for images you handle yourself, or pre-optimize them in your deployment script.
Your Next.js build shouldn’t be a mystery box. By systematically checking your dependency changes, profiling the build process, and understanding your hosting environment, you can turn a 2AM crisis into a 10-minute fix. If your build pipeline is consistently unpredictable or you need to architect a more resilient deployment workflow from the ground up, our team at Trove Deck Solution specializes in building robust, maintainable systems for SaaS founders—let’s talk about getting yours on solid footing.