Next.js Turbopack Stuck on Compiling? 5 Fixes (2026)

Quick fix: Stop the dev server, then run:

rm -rf .next node_modules/.cache
npm run dev

That clears the Turbopack cache and is the first thing to try. If it persists, the cause is a circular import, a barrel file pulling hundreds of icons, or a misconfigured experimental flag — all covered below.

Production build crashing instead? That's a different problem than a stuck dev server — skip straight to how to disable Turbopack for a production build.

Turbopack stuck on "Compiling..." is one of the most frustrating issues in Next.js 15/16 development. Your dev server starts, shows "Compiling /page", and then... nothing. It hangs indefinitely, blocking your entire development workflow.

This guide collects the fixes developers report and the Next.js documentation describes, plus a real reproduction of the documented --webpack opt-out and the false myths around NEXT_DISABLE_TURBOPACK. The exact dev-server freeze could not be reproduced in a clean project — the triggers are usually a corrupted cache, a circular import, or an oversized barrel file in a larger app — so the proof section below verifies only the build-level behavior that the article recommends.

This article is part of our comprehensive Deploying Next.js + Supabase to Production guide.

Tested environment#

Verified test — Passed

Framework

Next.js 16.2.10

Node

v24.13.1

Package manager

npm 11.8.0

OS / runtime

Windows 11 Pro / PowerShell 5.1

Command

next build --webpack

Proof screenshot

Source file: proofs/nextjs-turbopack-stuck-fix/terminal-webpack-build.txt

The reproduction was run in a disposable app under proofs/nextjs-turbopack-stuck-fix/repro/. It contains a single page, a minimal layout, and no custom webpack config. The only goal was to confirm that the documented --webpack flag really switches the production compiler, and that the common NEXT_DISABLE_TURBOPACK workaround is a myth.

How it was reproduced#

A clean Next.js 16 app was created in proofs/nextjs-turbopack-stuck-fix/repro/ and ran three commands. Each one was screenshotted as it ran.

1. Default production build#

Command: npm run build (which runs next build)

Result:

The header reads ▲ Next.js 16.2.10 (Turbopack).

2. Webpack fallback build#

Command: npm run build:webpack (alias for next build --webpack)

Result:

The header reads ▲ Next.js 16.2.10 (webpack). That is the documented opt-out actually working.

3. NEXT_DISABLE_TURBOPACK myth check#

Command: NEXT_DISABLE_TURBOPACK=1 npm run build

Result:

The header still reads ▲ Next.js 16.2.10 (Turbopack). The env var changed nothing.

All three builds succeeded with exit code 0.

The dev-server "stuck on compiling" symptom itself was not reproduced. A minimal app has no stale cache, no circular imports, and no barrel-file bloat, so it compiles in seconds. The sections above Solution 2 remain general troubleshooting guidance from the Next.js community and documentation, not from this direct reproduction.

What actually fixed it#

In this reproduction, the only "fix" verified is the documented compiler switch. Running next build --webpack genuinely replaced Turbopack with the Webpack pipeline for the production build. That is the escape hatch the article recommends when next start crashes after a green build or when a runtime module-resolution error appears only with Turbopack.

The cache-clearing steps in Solution 1 are reasonable first aid, but this test did not measure how often they clear the hang.

When this fix will not work#

Why Turbopack Gets Stuck#

Turbopack can hang for several reasons:

1. Corrupted Cache - .next cache conflicts with Turbopack
2. Circular Dependencies - Import cycles cause infinite loops
3. Large Files - Huge files or node_modules slow compilation
4. Memory Issues - Insufficient RAM for compilation
5. Incompatible Dependencies - Packages not compatible with Turbopack

Quick Diagnostic Steps#

## Check if it's actually stuck or just slow
## Wait 2-3 minutes first - large projects take time
 
## Check Node.js version (Next.js 16 requires 20.9+)
node --version
 
## Check memory usage
## Windows: Task Manager > Performance
## Mac: Activity Monitor
## Linux: htop or top
 
## Check for error messages
## Look in terminal for warnings/errors

Solution 1: Clear All Caches (Try This First)#

The most common fix is clearing caches:

## Stop the dev server (Ctrl+C)
 
## Delete all cache directories
rm -rf .next
rm -rf node_modules/.cache
rm -rf .turbo
 
## Clear npm cache
npm cache clean --force
 
## Reinstall dependencies
rm -rf node_modules
rm package-lock.json
npm install
 
## Start dev server
npm run dev

For Windows Users#

## Stop dev server (Ctrl+C)
 
## Delete cache directories
Remove-Item -Recurse -Force .next
Remove-Item -Recurse -Force node_modules\.cache
Remove-Item -Recurse -Force .turbo
 
## Clear npm cache
npm cache clean --force
 
## Reinstall
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install
 
## Start server
npm run dev

Solution 2: How to Disable Turbopack for a Production Build (next build --webpack)#

If clearing cache doesn't fix the hang — or the build succeeds but next start crashes with Cannot find module, MODULE_NOT_FOUND, or a 500 on the first request — the problem is a production runtime mismatch, not a dev-server hang. The documented opt-out is the --webpack flag. For a Docker container that instead exits with Cannot find module '/app/server.js', check the standalone server generation and copy before changing bundlers.

The fix: next build --webpack#

Pass the flag to the build command:

next build --webpack

That forces the Webpack production pipeline for that build. There is no NEXT_DISABLE_TURBOPACK=1 environment variable and no --no-turbopack flag in the Next.js codebase — those silently do nothing.

Where to put the flag (three options)#

1. package.json build script (recommended) — CI and Vercel pick it up automatically:

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

Keep dev on Turbopack for speed; only opt the build out.

2. One-off CLI run (local debugging):

next build --webpack
next start

Use this to confirm the diagnosis before committing the script change.

3. Vercel build command override:

If you cannot touch package.json, go to Settings → Build and Deployment → Build Command and set it to next build --webpack.

Verify the fallback actually happened#

Run the build and read the header. With Turbopack active you see:

▲ Next.js 16.x.x (Turbopack)

With --webpack the (Turbopack) marker disappears:

▲ Next.js 16.x.x (webpack)

This was verified with a clean Next.js 16.2.10 app in proofs/nextjs-turbopack-stuck-fix/repro/. The default build output is saved in terminal-normal-build.txt; the --webpack output is in terminal-webpack-build.txt.

Then curl the server locally:

next start &
sleep 2
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000
# Expected: 200

If you still get a 500, the issue is not Turbopack — treat it as a normal runtime error and debug the actual stack trace. If the stack trace mentions a chunk-loading failure (Loading chunk … failed), that is a different runtime issue — see Fix ChunkLoadError: Loading Chunk Failed in Next.js.

What does NOT work#

• NEXT_DISABLE_TURBOPACK=1 — not a real variable; silently ignored.
• next build --no-turbopack — not a real flag; recent versions error on unknown options.
• turbopack: false or experimental.turbo: false in next.config.mjs — there is no on/off boolean. In Next.js 16 the top-level turbopack key only holds loader options (resolveAlias, resolveExtensions, etc.).

Production crash debug checklist#

1. Read the first line after next start Ready. If it's a 500 with Cannot find module or MODULE_NOT_FOUND, suspect Turbopack first.
2. Re-run with next build --webpack && next start. If the failure disappears — confirmed.
3. Check next.config.mjs for a webpack(config) function. If present, your loader chain is the missing piece — Turbopack never ran it.
4. Check package.json for non-standard build scripts. Make sure --webpack actually reaches the next build invocation.
5. Check for stale experimental.turbo keys in next.config.mjs — the option was renamed to the top-level turbopack key in Next.js 15.3.0; the old name still works as an alias, but new config should use turbopack (version history).

When not to disable Turbopack#

If next start runs fine and your only issue is a slow build, do not disable Turbopack. Slow builds are usually a cold cache or an oversized barrel import. Measure before you switch: next build --profile only enables React production profiling, it does not profile the build itself; for the dev server, next dev --experimental-cpu-prof writes V8 CPU profiles to .next-profiles/ (and see Next.js + Supabase Performance Optimization 2026 for the full runtime-perf playbook). Disable only when the build is green and the runtime is broken.

Solution 3: Fix Circular Dependencies#

Circular imports cause Turbopack to hang:

Detect Circular Dependencies#

## Install circular dependency checker
npm install --save-dev madge
 
## Check for circular dependencies
npx madge --circular --extensions ts,tsx,js,jsx src/
 
## Output shows circular imports:
## Circular dependency found: 
## src/components/A.tsx > src/components/B.tsx > src/components/A.tsx

Fix Circular Imports#

// BAD: Circular dependency
// components/UserProfile.tsx
import { UserSettings } from './UserSettings'
 
export function UserProfile() {
  return <UserSettings />
}
 
// components/UserSettings.tsx
import { UserProfile } from './UserProfile'  // ❌ Circular!
 
export function UserSettings() {
  return <UserProfile />
}
 
// GOOD: Break the cycle
// components/UserProfile.tsx
import { UserSettings } from './UserSettings'
 
export function UserProfile() {
  return <UserSettings />
}
 
// components/UserSettings.tsx
// Remove import of UserProfile
// Use composition or context instead
 
export function UserSettings() {
  return <div>Settings</div>
}

Solution 4: Optimize Large Files and Dependencies#

Check File Sizes#

## Find large files in your project
find . -type f -size +1M -not -path "./node_modules/*" -not -path "./.next/*"
 
## Check node_modules size
du -sh node_modules
 
## Analyze bundle size
npm install --save-dev @next/bundle-analyzer
 
## Add to next.config.mjs:
import bundleAnalyzer from '@next/bundle-analyzer'
 
const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})
 
export default withBundleAnalyzer(nextConfig)
 
## Run analysis
ANALYZE=true npm run build

Optimize Dependencies#

// next.config.mjs
const nextConfig = {
  // Exclude large dependencies from server bundle
  serverExternalPackages: ['sharp', 'canvas', 'pdf-lib'],
 
  // Optimize package imports. `experimental.optimizePackageImports`
  // is the simpler option to `modularizeImports` (which still exists).
  // It is already on by default for common packages (lodash-es,
  // @mui/material, @mui/icons-material, lucide-react, …);
  // list extra ones here.
  experimental: {
    optimizePackageImports: ['lodash', '@mui/material', '@mui/icons-material'],
  },
}

Solution 5: Increase Memory Limit#

Turbopack may need more memory for large projects:

// package.json
{
  "scripts": {
    "dev": "NODE_OPTIONS='--max-old-space-size=4096' next dev --turbo",
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

For Windows#

// package.json
{
  "scripts": {
    "dev": "set NODE_OPTIONS=--max-old-space-size=4096 && next dev --turbo",
    "build": "set NODE_OPTIONS=--max-old-space-size=4096 && next build"
  }
}

Cross-Platform Solution#

## Install cross-env
npm install --save-dev cross-env
 
## Update package.json
{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--max-old-space-size=4096' next dev --turbo",
    "build": "cross-env NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

Solution 6: Update Dependencies#

Outdated packages can cause compatibility issues:

## Check for outdated packages
npm outdated
 
## Update Next.js to latest
npm install next@latest react@latest react-dom@latest
 
## Update all dependencies (careful!)
npm update
 
## Or use npm-check-updates
npx npm-check-updates -u
npm install

Check Turbopack Compatibility#

## Some packages don't work with Turbopack yet
## Check Next.js docs for compatibility:
## https://nextjs.org/docs/architecture/turbopack
 
## Common incompatible packages:
## - Some Webpack-specific loaders
## - Custom Webpack configurations
## - Some PostCSS plugins

Solution 7: Debug with Verbose Logging#

Enable detailed logging to identify the issue:

## Run with debug mode (Turbopack is already the default dev bundler in Next.js 16)
DEBUG=* npm run dev
 
## Or set environment variable
export DEBUG=*
npm run dev
 
## Check specific Next.js logs
DEBUG=next:* npm run dev
 
## Note: `npm run dev --turbo` does NOT pass --turbo to Next.js — npm keeps
## options placed before `--` for itself. Use `npm run dev -- --turbopack`.

Create Debug Configuration#

// next.config.mjs
const nextConfig = {
  // Enable detailed logging
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
  
  // Show more build info
  productionBrowserSourceMaps: true,
}

Common Mistakes#

• Mistake #1: Not waiting long enough - First compile can take 2-3 minutes for large projects

• Mistake #2: Using incompatible Webpack config - Turbopack doesn't support all Webpack features

• Mistake #3: Not checking Node.js version - Next.js 16 requires Node.js 20.9 or higher ("engines": { "node": ">=20.9.0" } in the next package)

• Mistake #4: Ignoring circular dependencies - These cause infinite compilation loops

• Mistake #5: Running multiple dev servers - Kill all Node processes before restarting

Advanced Debugging Techniques#

Using Chrome DevTools for Turbopack Issues#

// Enable detailed logging in next.config.mjs
const nextConfig = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
  
  // Show webpack build info
  webpack: (config, { dev, isServer }) => {
    if (!dev) {
      console.log('Building for:', isServer ? 'server' : 'client')
    }
    return config
  },
}
 
export default nextConfig

Profiling Turbopack Performance#

## Generate performance profile
node --prof node_modules/.bin/next dev --turbo
 
## Analyze the profile
node --prof-process isolate-*.log > profile.txt
 
## Check which functions take the most time
grep -E "ticks|name" profile.txt | head -50

Turbopack Configuration Optimization#

In Next.js 16 the Turbopack options live under the top-level turbopack key; the older experimental.turbo name still works as an alias, but new configuration should use turbopack. The documented options include loader rules, resolveAlias, and resolveExtensions:

// next.config.mjs
const nextConfig = {
  turbopack: {
    // Resolve aliases for faster, unambiguous imports
    resolveAlias: {
      '@': './src',
    },
 
    // Restrict the extensions Turbopack tries during resolution
    resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
  },
}
 
export default nextConfig

Two things people ask for that don't exist: there is no excludeFiles option and no per-route disable — Turbopack is on or off for the whole compiler, via the --webpack flag. If a stale experimental.turbo block is sitting in your config from Next.js 14/15, move it to the top-level turbopack key (npx @next/codemod@latest next-experimental-turbo-to-turbopack . does it for you): the old name is still read as an alias, so leaving it there is not what makes the dev server hang.

Preventing Turbopack Issues#

Best Practices for Stable Development#

1. Keep dependencies updated

   bash

   npm update
   npm install next@latest

2. Avoid circular dependencies

   bash

   npx madge --circular --extensions ts,tsx src/

3. Monitor file sizes

   bash

   find . -type f -size +1M -not -path "./node_modules/*"

4. Use consistent import patterns

   typescript

   // ✅ GOOD: Consistent absolute imports
   import { Button } from '@/components/Button'
   import { formatDate } from '@/lib/utils'
    
   // ❌ BAD: Mixed relative and absolute
   import { Button } from '../components/Button'
   import { formatDate } from '@/lib/utils'

5. Limit custom Webpack configuration

   javascript

   // ❌ AVOID: Complex webpack config
   webpack: (config) => {
     config.plugins.push(new CustomPlugin())
     config.module.rules.push(customRule)
     return config
   }
    
   // ✅ PREFER: Use Next.js built-in features
   // For tree-shaking large icon/utility libs, use `experimental.optimizePackageImports`
   // in next.config.js (simpler than `modularizeImports`, which still exists):
   //   experimental: { optimizePackageImports: ['lucide-react', 'date-fns'] }

Troubleshooting Checklist#

Use this checklist when Turbopack gets stuck:

□ Wait 2-3 minutes (first compile is slow)
□ Check Node.js version (Next.js 16 requires 20.9+)
□ Check available memory (need 2GB+)
□ Clear .next directory
□ Clear node_modules/.cache
□ Clear .turbo directory
□ Reinstall dependencies
□ Check for circular dependencies
□ Check for large files (>1MB)
□ Disable Turbopack temporarily
□ Check for incompatible packages
□ Update Next.js to latest
□ Check deployment logs for errors
□ Enable debug logging
□ Profile with Node.js profiler
□ Check for network issues
□ Restart dev server

Handling "An unexpected Turbopack error occurred. Please see the output of next dev for more details."#

That opaque red-box message means Turbopack hit an internal panic it could not surface as a clear diagnostic, so it asks you to look at the terminal where you ran next dev. The fix is rarely a single keystroke — it is a three-step drill to turn a vague panic into a specific root cause. If the terminal instead reports a webpack configuration with no Turbopack configuration, follow the webpack-hook migration diagnosis before treating that explicit guard as an internal panic.

Step 1: Reread the terminal output fully#

Scroll up past the repeated "Compiling…" lines. Look for any of these keywords, which are the real clues:

• Syntax error or Binding not found — usually a dependency that imports a module not exported by its package (common after a major version bump of a UI kit or icon library).
• invariant or workUnitAsyncStorage — a dependency calling headers(), cookies(), or draftMode() at module scope where no request context exists. The Next.js 16 /_not-found prerender fix traces one confirmed repro to react-instantsearch-nextjs@1.x doing exactly this under Turbopack.
• Cannot find module — a resolution mismatch Turbopack cannot resolve; Webpack may have tolerated it via a custom loader or alias in next.config.mjs. Check your config for a webpack(config) function — Turbopack ignores it.
• Failed to execute 'measure' — a performance-measurement panic that happens when a route calls notFound() during client navigation. That is a separate runtime crash with its own fix at Fix Next.js 'Cannot Have a Negative Time Stamp' Error.

If the terminal shows only the generic message and no preceding error line, stop next dev, clear the .next directory, and restart. A stale partial compile can cause Turbopack to hit an internal invariant on the next run.

Step 2: Isolate the triggering page#

Comment out half your page.tsx exports and restart next dev. If the error disappears, the cause lives in the half you just removed. Binary-search the suspect set until you isolate the single component, import, or hook that triggers the panic. A single unconditional headers() call inside a third-party SearchProvider wrapper is a frequent culprit — wrap it in a dynamic import with { ssr: false } to defer it to the client, where request context is irrelevant.

Step 3: If the terminal is still empty, switch to Webpack for diagnosis#

Run next dev --webpack. Webpack’s error output is often more verbose for the same fault. If it emits a clear Module not found or SyntaxError, fix that directly. If the error vanishes, the trigger is Turbopack-specific, and you need to disable Turbopack for the build while raising a minimal reproduction for the Next.js team. The --webpack flag is the only documented opt-out — NEXT_DISABLE_TURBOPACK=1 and turbopack: false do nothing, as confirmed in the article’s reproduction above.

Conclusion#

Turbopack stuck on compiling is usually caused by corrupted cache, circular dependencies, or memory issues. The fastest first step is clearing all caches (.next, node_modules/.cache, .turbo) and reinstalling dependencies. This test did not reproduce the hang, so treat that step as community advice, not a measured result.

If the issue persists, check for circular imports with madge, increase memory limits, or temporarily disable Turbopack. For production projects where next start crashes after a green build, run next build --webpack to fall back to the Webpack pipeline — that is the only documented opt-out in Next.js 16, and a clean 16.2.10 app confirms that the compiler header really switches from (Turbopack) to (webpack).

Monitor your compilation times and file sizes to prevent future issues. Turbopack is powerful and now the default, but don't hesitate to fall back to Webpack when you hit a compatibility wall.

Further reading: Next.js "Server Is Running Out of Memory" Fix (2026).