How to Fix Next.js Build Failed Errors

In this tutorial, you'll learn about How to Fix Next.js Build Failed Errors. We cover key concepts, practical examples, and best practices.

The Problem

next build exits with Build error occurred or Error: Export encountered errors. The build may fail during the compilation phase (TypeScript or ESLint errors), the static generation phase (a page throws during getStaticProps), or the API route bundling phase. Common causes include strict TypeScript errors that are not fixed, ESLint violations configured to fail the build, and pages that exceed the default data size limits.

Quick Fix

1. Read the full error log

npm run build 2>&1 | tail -50

Expected output (error):

> Build error occurred
Error: Failed to compile
./src/pages/index.tsx:12:8
Type error: Type 'string | undefined' is not assignable to type 'string'.
 12 |   const name: string = user.name;

2. Fix TypeScript errors before building

npx tsc --noEmit

Expected output:

src/pages/index.tsx:12:8 - error TS2322: Type 'string | undefined' is not assignable to type 'string'.

Fix all type errors, then rebuild.

3. Temporarily relax ESLint during builds

In next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
    eslint: {
        ignoreDuringBuilds: true,
    },
    typescript: {
        ignoreBuildErrors: false,
    },
    images: {
        unoptimized: true,
    },
    output: 'standalone',
};

module.exports = nextConfig;

4. Handle large pages that exceed static generation limits

If Error: Export encountered errors mentions a specific page, reduce its data size:

export async function getStaticProps() {
    const allPosts = await fetchAllPosts();

    // Paginate to keep the page size manageable
    const posts = allPosts.slice(0, 50);

    return {
        props: { posts },
        revalidate: 60,
    };
}

5. Clear Next.js build cache

rm -rf .next
npm run build

Expected output:

✓ Compiled successfully
✓ Static generation complete (5 pages)
✓ Collecting page data
✓ Finalizing page optimization

6. Check the Node.js version

node --version

Next.js 14+ requires Node.js 18.17 or higher. Use nvm to switch:

nvm install 20
nvm use 20

7. Debug with verbose output

NODE_OPTIONS='--trace-warnings' next build

8. Check for missing environment variables referenced at build time

grep -r "process.env.NEXT_PUBLIC_" src/ | head -20

For each NEXT_PUBLIC_* variable, ensure a default value is provided or the variable is set at build time:

NEXT_PUBLIC_API_URL=https://api.example.com next build

9. Clean the .next cache and rebuild

rm -rf .next
next build

This resolves issues where stale compilation artifacts cause ModuleNotFound errors after switching branches.

Prevention

• Run npx tsc --noEmit and npx next lint before every build to catch errors early
• Keep Next.js and React in the same major version range (check the package.json peer dependencies)
• Use output: 'standalone' for Docker-based deployments to reduce the final image size
• Add .next/ to .gitignore — never commit build artifacts
• Run a production build locally with NODE_ENV=production next build before merging into the main branch