Understanding npm “Could not resolve dependency” installation errors

I am working on a task to upgrade Next.js from version 12.x to 13.x (14.x is out, but I’m not ready for that yet) and as I ran into dependency issues, I didn’t find a simple explanation of how exactly you understand the “could not resolve dependency” error in npm. Here’s what it looks like:

$ npm i
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: react-sortable-hoc@2.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!   peer react@">=16.8.0" from @dnd-kit/accessibility@3.1.0
npm ERR!   node_modules/@dnd-kit/accessibility
npm ERR!     @dnd-kit/accessibility@"^3.1.0" from @dnd-kit/core@6.1.0
npm ERR!     node_modules/@dnd-kit/core
npm ERR!       @dnd-kit/core@"^6.1.0" from the root project
npm ERR!       1 more (@dnd-kit/sortable)
npm ERR!   79 more (@dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, ...)
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.3.0 || ^17.0.0" from react-sortable-hoc@2.0.0
npm ERR! node_modules/react-sortable-hoc
npm ERR!   react-sortable-hoc@"^2.0.0" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: react@17.0.2
npm ERR! node_modules/react
npm ERR!   peer react@"^16.3.0 || ^17.0.0" from react-sortable-hoc@2.0.0
npm ERR!   node_modules/react-sortable-hoc
npm ERR!     react-sortable-hoc@"^2.0.0" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

What it means in human language:

“While resolving one package, I found a dependency that doesn’t fit what the library I just mentioned requires”

npm ERR! While resolving: react-sortable-hoc@2.0.0
npm ERR! Found: react@18.2.0

This is a bit confusing at first read, because I’m like “you found something, what’s the problem?” We must read further to find out. When we see:

npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.3.0 || ^17.0.0" from react-sortable-hoc@2.0.0

That’s the dependency (react-sortable-hoc) requires, and the associated versions accepted.

In this case, to use react-sortable-hoc@2.0.0, we need either react@16 or react@17, but back at the top with out Found we know we have react@18 (because we’re upgrading things).

And here are your resolution options:

npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps

So I can do some investigation and fixin’, or update the build to allow this situation (less ideal, possibly risky).

To resolve the situation, I go and check react-sortable-hoc to see if it has upgrade available, but the library recommends using a different library to solve what it does (for good reasons laid out in its README). And so the dependency resolution journey continues … but maybe this explanation of understanding “Could not resolve dependency” in npm helps a future reader!