Next.js Turbopack Stuck on Compiling How to Fix#

Turbopack stuck on "Compiling..." is one of the most frustrating issues in Next.js 15 development. Your dev server starts, shows "Compiling /page", and then... nothing. It hangs indefinitely, blocking your entire development workflow. This guide provides 5 proven solutions that work in production.

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

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 (requires 18.17+)
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 (Works 80% of Time)#

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: Disable Turbopack Temporarily#

If clearing cache doesn't work, disable Turbopack:

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Remove or comment out turbopack option
  // experimental: {
  //   turbo: {},
  // },
}

export default nextConfig

Start Without Turbopack Flag#

## Instead of: npm run dev --turbo
## Use: npm run dev

## Or update package.json:
{
  "scripts": {
    "dev": "next dev",  // Remove --turbo flag
    "dev:turbo": "next dev --turbo",  // Keep as separate command
    "build": "next build",
    "start": "next start"
  }
}

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
  modularizeImports: {
    'lodash': {
      transform: 'lodash/{{member}}',
    },
    '@mui/material': {
      transform: '@mui/material/{{member}}',
    },
  },
}

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
DEBUG=* npm run dev --turbo

## Or set environment variable
export DEBUG=*
npm run dev --turbo

## Check specific Next.js logs
DEBUG=next:* npm run dev --turbo

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 - Requires Node 18.17 or higher

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

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

FAQ#

How long should Turbopack compilation take?#

First compilation: 30 seconds to 3 minutes depending on project size. Subsequent hot reloads: 1-5 seconds. If it takes longer, something is wrong.

Is Turbopack stable for production?#

Turbopack is for development only in Next.js 15. Production builds still use Webpack. It's stable for dev but may have edge cases.

Should I use Turbopack or Webpack?#

Turbopack is faster for development but less mature. If you encounter issues, fall back to Webpack (npm run dev without --turbo flag).

Can I use Turbopack with custom Webpack config?#

Limited support. Many Webpack plugins and loaders don't work with Turbopack. Check Next.js docs for compatibility.

How do I completely disable Turbopack?#

Remove --turbo flag from dev script and remove any turbo configuration from next.config.mjs.

Related Articles#

• Fix Next.js Build Error Module Not Found After Deploy
• Resolve Next.js Hydration Mismatch Errors Complete Guide
• Deploy Next.js 15 to Vercel Without Environment Variable Errors
• Next.js Performance Optimization: 10 Essential Techniques

Conclusion#

Turbopack stuck on compiling is usually caused by corrupted cache, circular dependencies, or memory issues. The fastest fix is clearing all caches (.next, node_modules/.cache, .turbo) and reinstalling dependencies.

If that doesn't work, check for circular imports using madge, increase memory limits, or temporarily disable Turbopack. For production projects, always have a fallback to standard Webpack mode.

Monitor your compilation times and file sizes to prevent future issues. Turbopack is powerful but still maturing, so don't hesitate to fall back to Webpack if needed.