Solved: Next.js Build Fails with Terser Invalid Unicode Code Point Error

You've tested your Next.js application locally—everything builds perfectly. You push to your CI/CD pipeline, kick off a Docker build, and suddenly you're staring at this cryptic error:

invalid unicode code point at line 1 column 43757

The build crashes. No stack trace pointing to your code. Just Terser complaining about Unicode during minification. If you're reading this, you've likely already wasted hours trying to figure out which file is causing the problem.

Here's the frustrating part: this error almost exclusively occurs in Dockerized environments, particularly when using Alpine-based Node.js images. Your local machine builds the same code without issues. This isn't a bug in your code—it's an environmental incompatibility between your Docker base image and Next.js's minification process.

This article breaks down exactly why the Next.js Terser Invalid Unicode Code Point error happens, why it's Docker-specific, and how to fix it without compromising your production build quality.

The Problem — Build Failure with Terser Throwing an 'Invalid Unicode Code Point' Error During Minification

When running npm run build or next build inside a Docker container, the build process fails during the minification phase. The error looks something like this:

> next build
 
   ▲ Next.js 14.2.5
 
   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types
 ✓ Collecting page data
   Generating static pages (0/8)
 
Error: invalid unicode code point at line 1 column 43757
    at Terser.minify (/app/node_modules/terser/lib/minify.js:104:15)

This error is particularly insidious because:

1. It provides no actionable file reference — "line 1 column 43757" tells you nothing about which source file is problematic
2. It only manifests in specific environments — your local macOS or Windows machine likely builds fine
3. It appears random — sometimes it occurs after adding new dependencies, other times after seemingly unrelated changes

The issue was reported on GitHub (#69263) where developers consistently noted the problem appears when deploying to cloud VMs using Docker, particularly with Debian or Alpine-based containers.

What the Error Actually Means

Terser, the JavaScript minifier, processes your bundled code and encounters a byte sequence it interprets as an invalid Unicode code point. This typically happens when:

• The underlying C library interprets byte sequences differently than expected
• Locale settings don't properly support UTF-8 encoding
• Character encoding mismatches occur between the build environment and the source code

The column number (43757 in the example) points to a position in a minified bundle, not your source code. Tracking down the exact problematic character is nearly impossible without significant debugging effort.

Why This Happens — Incompatibility Between Minification and Specific Docker Base Images

The root cause comes down to a fundamental difference in how different Linux distributions handle low-level C library operations, particularly around Unicode and character encoding.

Alpine Linux and musl libc

Many developers choose Alpine-based Docker images (node:alpine, node:20-alpine) for their small footprint. Alpine images can be 5-10x smaller than their Debian equivalents. However, Alpine uses musl libc instead of the standard glibc that most Linux distributions use.

This difference matters because:

1. musl has stricter Unicode handling — Some byte sequences that glibc tolerates are rejected by musl
2. Native bindings may behave differently — Terser and SWC include native components that can produce different results
3. Default locale configurations differ — Alpine ships with minimal locale support by default

Here's what a typical problematic Dockerfile looks like:

# ❌ BROKEN: Alpine base image causes Unicode minification issues
FROM node:20-alpine
 
WORKDIR /app
 
COPY package*.json ./
RUN npm ci
 
COPY . .
 
# This build step fails with "invalid unicode code point"
RUN npm run build
 
EXPOSE 3000
CMD ["npm", "start"]

The swcMinify Confusion

You might notice that Next.js uses SWC (a Rust-based compiler) for minification by default, not Terser. So why does the error mention Terser?

The answer is that SWC doesn't handle all minification scenarios. Certain code patterns, particularly from third-party packages, may still be processed by Terser as a fallback. Additionally, some Next.js configurations or plugins (like next-pwa) can introduce Terser into the build pipeline.

Even with swcMinify: true explicitly set in your config, the error can still occur because:

• External packages may include pre-bundled code that bypasses SWC
• Service worker generation often uses separate minification
• Some Next.js internal processes still invoke Terser for specific files

The Docker-Specific Nature

Why does this only happen in Docker? Your local development environment likely runs on macOS or Windows (or a standard Linux distribution with glibc). These environments have complete locale support and use the same C library conventions that Node.js and its native dependencies were primarily developed against.

When you build inside an Alpine container:

1. The LANG and LC_ALL environment variables may be unset
2. The minimal musl libc interprets certain byte sequences differently
3. Native bindings compiled against glibc may have subtle behavioral differences

The Solution — Adjusting next.config.js and Verifying Docker Environment Settings

There are several approaches to fixing the Next.js Terser Invalid Unicode Code Point error, ranging from quick workarounds to proper long-term solutions.

Solution 1: Switch to a glibc-Based Node Image (Recommended)

The most reliable fix is to use a Debian-based Node.js image instead of Alpine:

# ✅ FIXED: Debian-based image with proper Unicode support
FROM node:20-slim
 
WORKDIR /app
 
COPY package*.json ./
RUN npm ci
 
COPY . .
 
RUN npm run build
 
EXPOSE 3000
CMD ["npm", "start"]

The node:20-slim image is a minimal Debian-based image that's larger than Alpine but still reasonably sized (approximately 200MB vs 50MB for Alpine). It uses glibc and has proper locale support out of the box.

Trade-offs:

• Pros: Eliminates the Unicode issue entirely, better compatibility with native modules
• Cons: Larger image size, though this is often negligible in production environments

Solution 2: Configure Locale in Alpine (Partial Fix)

If you absolutely must use Alpine for image size reasons, you can try installing locale support:

# ⚠️ PARTIAL FIX: Alpine with locale support
FROM node:20-alpine
 
# Install locale support
RUN apk add --no-cache icu-libs icu-data-full
 
# Set locale environment variables
ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8
 
WORKDIR /app
 
COPY package*.json ./
RUN npm ci
 
COPY . .
 
RUN npm run build
 
EXPOSE 3000
CMD ["npm", "start"]

Note: This approach doesn't always work because the underlying musl libc behavior remains unchanged. The locale settings help some scenarios but don't address the fundamental glibc/musl incompatibility.

Solution 3: Disable Minification (Development/Debugging Only)

As a temporary workaround for debugging or development environments, you can disable minification entirely:

// next.config.js
// ❌ NOT RECOMMENDED FOR PRODUCTION: Disables all minification
/** @type {import('next').NextConfig} */
const nextConfig = {
  swcMinify: false,
 
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.optimization.minimize = false;
    }
    return config;
  },
};
 
module.exports = nextConfig;

Warning: This produces significantly larger bundles and should never be used in production. It's only useful for confirming that minification is indeed the source of the problem.

Solution 4: Multi-Stage Build with Debian Builder

For the best of both worlds—small runtime image but reliable builds—use a multi-stage Dockerfile:

# ✅ BEST PRACTICE: Multi-stage build
# Stage 1: Build using Debian-based image
FROM node:20-slim AS builder
 
WORKDIR /app
 
COPY package*.json ./
RUN npm ci
 
COPY . .
 
RUN npm run build
 
# Stage 2: Production runtime (can even use Alpine here since we're not building)
FROM node:20-alpine AS runner
 
WORKDIR /app
 
ENV NODE_ENV=production
 
# Copy only necessary files from builder
COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
 
EXPOSE 3000
CMD ["node", "server.js"]

This approach:

• Uses Debian for the build phase where minification occurs
• Uses Alpine for the runtime where image size matters
• Produces reliable builds with minimal runtime footprint

Note: This requires output: 'standalone' in your next.config.js:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
};
 
module.exports = nextConfig;

Prevention & Best Practices — Standardizing Docker Base Images to Avoid OS-Specific Minification Bugs

Encountering the Next.js Terser Invalid Unicode Code Point error is a symptom of a broader issue: environment inconsistency between development and production. Here's how to prevent this class of problems:

Standardize Your Base Images

Choose one of these strategies and apply it consistently across all projects:

Strategy A: Always Use Debian-Based Images

# Preferred base images for Next.js applications
FROM node:20-slim        # Minimal Debian, ~200MB
FROM node:20-bookworm    # Full Debian, ~900MB
FROM node:20             # Default Debian, ~900MB

Strategy B: Multi-Stage with Alpine Runtime If image size is critical, use the multi-stage approach shown above. Build with Debian, run with Alpine.

Set Explicit Locale Variables

Regardless of which base image you use, always set locale environment variables:

ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8

This ensures consistent character encoding behavior across all environments.

Lock Your Node.js Version

Use specific version tags, not latest or major version tags:

# ❌ Avoid: Can change unexpectedly
FROM node:latest
FROM node:20
 
# ✅ Prefer: Pinned version for reproducibility
FROM node:20.10.0-slim

Test Builds in CI Before Deployment

Add a build verification step to your CI pipeline that mirrors your production Docker build:

# .github/workflows/build-test.yml
name: Build Test
 
on: [push, pull_request]
 
jobs:
  docker-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Build Docker image
        run: docker build -t myapp:test .
 
      - name: Verify container starts
        run: |
          docker run -d --name test-container -p 3000:3000 myapp:test
          sleep 10
          curl -f http://localhost:3000 || exit 1

Document Your Environment Requirements

Add a section to your project's README specifying the tested Docker base images:

## Docker Requirements
 
This project requires a glibc-based Node.js image for building.
 
**Tested Base Images:**
 
- `node:20-slim` ✅
- `node:20-bookworm` ✅
- `node:20-alpine` ❌ (Unicode minification errors)

Key Takeaways

• The "Invalid Unicode Code Point" Terser error is environment-specific, almost always occurring in Docker containers using Alpine Linux or other musl-based distributions
• Alpine's musl libc handles Unicode differently than glibc, causing minification to fail on byte sequences that work fine in standard development environments
• The fastest fix is switching from node:alpine to node:slim or another Debian-based image—this resolves the issue without code changes
• Multi-stage builds let you have both: reliable Debian builds and small Alpine runtime images
• Always set LANG=C.UTF-8 and LC_ALL=C.UTF-8 in your Dockerfiles regardless of base image choice

Next Steps

1. Audit your Dockerfiles — Check if any use Alpine-based images and consider switching to Debian-based alternatives
2. Implement multi-stage builds — If image size is a concern, configure builds to use Debian and runtime to use Alpine
3. Add CI build verification — Ensure your build pipeline catches these errors before they reach production
4. Pin your base image versions — Avoid floating tags that can introduce unexpected behavioral changes
5. Review the GitHub issue (#69263) — Stay updated on any upstream fixes or new workarounds from the Next.js team