So, Why Does This Nightmare Happen?

This isn’t about you writing bad code. This is a structural problem with how Node resolves dependencies. Your `package.json` might list "some-cool-library": "^1.0.0". But that library has its *own* dependencies. And those have *their own* dependencies. You get the picture. This creates a dependency tree.

The problem is when two different branches of that tree require conflicting versions of the same package, especially a type-definition package like @types/react or @types/node. For example:

• Your app directly uses @types/react@18.0.0.
• A dependency, let’s call it old-ui-kit, depends on @types/react@17.0.0.

NPM or Yarn will cleverly install both versions in your node_modules folder to satisfy everyone. But when the TypeScript compiler (`tsc`) runs, it can get confused. It might pick up one version for one file and the other version for another, leading to bizarre type errors where a type from one version is declared incompatible with the “same” type from another.

PRO TIP: Before you change a single line of code, run a command like npm ls @types/react or yarn why @types/react. This will show you every instance of that package in your dependency tree and who pulled it in. This is your treasure map.

The Fixes: From Band-Aid to Surgery

I’ve seen teams handle this in a few ways. Here are the three main strategies, ranging from “get me unblocked now” to “let’s fix this forever.”

Solution 1: The Quick Fix (Forcing a Resolution)

This is the fastest way to get your build passing again. You can explicitly tell your package manager, “Hey, no matter what anyone asks for, only install ONE version of this package.” This is done using overrides in NPM or resolutions in Yarn.

You’d add this to your root package.json:

// In your package.json (for NPM)
"overrides": {
  "@types/react": "18.0.0"
}

// Or for Yarn Classic/Berry
"resolutions": {
  "@types/react": "18.0.0"
}

After adding this, delete your node_modules and your lock file (package-lock.json or yarn.lock) and run npm install or yarn install again. This forces every part of your dependency tree to use the single version you specified.

Warning: This is a powerful tool. You are essentially ignoring a dependency’s explicit requirements. This usually works fine for @types packages, but forcing a version of a library with actual runtime code can cause subtle bugs if there are breaking changes between versions.

Solution 2: The ‘Right’ Fix (Auditing and Upgrading)

The quick fix is a Band-Aid. The permanent solution is to find the outdated dependency that’s causing the problem and upgrade it. Using the npm ls command from before, you identify the culprit (e.g., old-ui-kit). Now you have a few options:

• Check if there’s a newer version of old-ui-kit that uses the correct version of @types/react. Upgrade it.
• If the library is unmaintained, find a modern replacement and do the work to migrate.
• If it’s an internal company package, go talk to the team that owns it and get them to update their dependencies.

This is the “eat your vegetables” approach. It takes more time and coordination, and you might need to convince your Product Manager that this “tech debt” work is critical. But it’s the only way to keep your dependency tree healthy in the long run.

Solution 3: The ‘Nuclear’ Option (Patching)

Okay, sometimes you’re truly stuck. The conflicting package is from a third party that won’t update it, and you can’t replace it right now. For these desperate times, we have tools like patch-package.

This tool lets you make direct changes to a file inside node_modules and then save that change as a patch file that gets re-applied automatically every time someone runs npm install. For a type conflict, you might go into the offending index.d.ts file in the old package and manually change the types to match what you need. It feels dirty, because it is. But sometimes, it’s the only thing that gets the production build to pass at 3 AM.

The workflow is simple:

1. Install patch-package.
2. Manually edit the problematic file inside node_modules.
3. Run npx patch-package old-ui-kit.
4. This creates a patches/old-ui-kit+1.2.3.patch file. Commit this file.
5. Add a postinstall script to your package.json: "postinstall": "patch-package".

This is a last resort. It’s brittle—the patch can break when you update the package. But when the alternative is a broken build, it’s a tool you need to have in your back pocket.

Which Path Should You Choose?

To make it easier, here’s how I think about it:

Look, dependency management is a pain. It’s one of the unglamorous parts of our job. But understanding why these cryptic errors happen and knowing you have a toolbox of solutions is what separates a junior engineer from a senior one. So next time TypeScript yells at you for something that isn’t your fault, take a deep breath, run npm ls, and pick your weapon of choice. You’ve got this.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions