How to Fix: Error with the latest version of @jridgewell/gen-mapping ( @jridgewell/gen-mapping@0.3.6 )

The crash after creating a fresh Next.js 15 app usually comes from a dependency-resolution mismatch: your install pulls in @jridgewell/gen-mapping@0.3.6, but another package in the source-map toolchain expects a different behavior or compatible subdependency set. The result is a startup failure even though the project was generated with the default create-next-app flow.

Understanding the Root Cause

This issue is typically not caused by your application code. It happens in the build and transpilation dependency chain used by Next.js. Packages related to source maps, bundling, and code transformation often depend on @jridgewell/gen-mapping either directly or transitively.

With a fresh install, your package manager may resolve @jridgewell/gen-mapping 0.3.6 into the lockfile because it satisfies a semver range declared by another dependency. If one of the surrounding packages was tested against an earlier patch version, or if the lockfile pulls an inconsistent set of related packages, Next.js can fail during dev server startup or compilation.

In practice, the bug usually appears because of one of these technical conditions:

• A transitive dependency regression in the source-map package graph.
• Different resolution behavior between npm, pnpm, and Yarn.
• An existing lockfile or cached install keeping an incompatible dependency tree.
• Node.js version differences exposing stricter runtime behavior during package execution.

The key point is that Next.js 15 itself may be fine, but the exact dependency tree installed on your machine is not.

Step-by-Step Solution

The safest fix is to force a known-good version of @jridgewell/gen-mapping, remove the current dependency tree, and reinstall cleanly.

1. Check which version is installed

npm ls @jridgewell/gen-mapping

If you use pnpm or Yarn, run:

pnpm why @jridgewell/gen-mapping

yarn why @jridgewell/gen-mapping

2. Remove current install artifacts

rm -rf node_modules package-lock.json .next

On Windows PowerShell:

rmdir /s /q node_modules
Del package-lock.json
rmdir /s /q .next

3. Pin a stable version using overrides

If npm is your package manager, add this to package.json:

{
  "overrides": {
    "@jridgewell/gen-mapping": "0.3.5"
  }
}

If you use pnpm:

{
  "pnpm": {
    "overrides": {
      "@jridgewell/gen-mapping": "0.3.5"
    }
  }
}

If you use Yarn:

{
  "resolutions": {
    "@jridgewell/gen-mapping": "0.3.5"
  }
}

4. Reinstall dependencies

npm install

Or:

pnpm install

yarn install

5. Start the development server again

npm run dev

6. Verify the override worked

npm ls @jridgewell/gen-mapping

You want to confirm that the resolved version is now 0.3.5 instead of 0.3.6.

7. Optional: upgrade Next.js and related packages

If a newer patch of Next.js has already absorbed the dependency fix, update and reinstall:

npm install next@latest react@latest react-dom@latest

Then remove install artifacts again and reinstall cleanly if needed.

Recommended minimal package.json fix

{
  "name": "my-next-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "15.0.0",
    "react": "18.3.1",
    "react-dom": "18.3.1"
  },
  "overrides": {
    "@jridgewell/gen-mapping": "0.3.5"
  }
}

If you want to confirm whether this is already tracked upstream, check the relevant package release notes and dependency issue threads on Next.js GitHub and gen-mapping GitHub.

Common Edge Cases

1. The error persists after adding overrides

This usually means the lockfile or package manager cache still points to the older tree. Delete node_modules, the lockfile, and your build folder, then reinstall.

2. Different team members cannot reproduce the problem

That often happens when developers are using different package managers or different Node.js versions. Standardize both across the team.

3. CI fails but local development works

Your CI environment may be rebuilding the dependency graph from scratch while your machine is using a cached install. Commit the lockfile and enforce the override in version control.

4. The project uses pnpm and ignores npm overrides

pnpm uses its own override configuration. Make sure the override is declared under the correct pnpm.overrides section.

5. You are on an unsupported Node version

Next.js 15 expects a modern Node runtime. Verify your version:

node -v

If needed, switch to an LTS version recommended by the framework documentation on Next.js Docs.

6. Another package forces 0.3.6 again

Run a dependency trace with npm ls, pnpm why, or yarn why to identify which package is pulling it in. If necessary, pin both the direct parent package and @jridgewell/gen-mapping.

FAQ

Is this a Next.js bug or a gen-mapping bug?

It is usually a dependency compatibility issue between Next.js tooling and the resolved transitive version of @jridgewell/gen-mapping. The visible failure occurs in Next.js, but the root problem is often in the resolved package graph.

Why does a brand-new app fail if I did nothing custom?

Because modern JavaScript apps rely on many transitive dependencies. Even when your app code is empty, your package manager still resolves a large dependency tree, and one problematic patch version can break startup.

Should I downgrade Next.js?

Usually no. First try a clean reinstall and a targeted override for @jridgewell/gen-mapping. Downgrading Next.js should be a last resort unless the framework release itself is confirmed broken.

The fastest reliable fix is to pin @jridgewell/gen-mapping to 0.3.5, wipe the install state, and reinstall. That restores a stable dependency graph while you wait for an upstream patch to fully normalize the toolchain.