npm audit fix --force: What It Changes, and How to Undo It
npm audit fix --force lets npm move packages outside the version ranges in your package.json, including to new major versions, to clear the audit. It does that for every package it can, in one go, without asking which upgrades you meant. That's why it fixes the count and breaks the app. Run it on a branch after a dry run, or skip it and upgrade the one or two packages that need it by hand.
This post is the long version of one section of how to fix npm vulnerabilities: exactly what the flag does, how to read what it's about to do, how to get back to where you were, and the few cases where it's the right tool.
What npm audit fix --force actually does
Plain npm audit fix stays inside the ranges your package.json already allows. If express is listed as ^4.17.1, it can move to 4.22.3, because ^4 permits that. It can't move to 5.x, and it can't move anything whose version is pinned exactly.
The npm docs describe --force as the way to "have audit fix install SemVer-major updates to toplevel dependencies, not just SemVer-compatible ones". Two words there matter. Toplevel: it changes the packages in your own package.json, and the transitive ones follow. SemVer-major: a new major version is where package authors are allowed to break things.
The general description of the force option in the same docs is blunter: "If you don't have a clear idea of what you want to do, it is strongly recommended that you do not use this option!"
The three lines npm prints, and what each means
Run npm audit and each finding ends with one of three lines. They tell you in advance whether --force is involved.
fix available via `npm audit fix`The fix fits inside your current ranges. Plain npm audit fix will apply it.
fix available via `npm audit fix --force`
Will install express@4.22.3, which is outside the stated dependency rangeThe fix is a version your package.json doesn't allow, but not a new major. This is common when a generator or a lockfile-first workflow pinned exact versions ("express": "4.17.1"). The upgrade is probably safe; the flag is needed only because of the pin. Loosen the range or run npm install express@4 instead.
fix available via `npm audit fix --force`
Will install mocha@12.0.3, which is a breaking changeThe fix is a new major version. "Breaking change" is npm's label for any SemVer-major jump; it doesn't know whether your code uses the parts that changed. This is the one that needs a changelog and a test run.
A fourth line, No fix available, means no released version resolves the advisory, and --force can't help. The options for that case are replacing, overriding, removing, or accepting with a note.
Why it breaks apps
Three reasons, and they stack.
It applies every upgrade at once. If four packages need a major bump, you get all four in one commit. When the build fails, you don't know which one did it.
It rewrites your version choices. Your package.json is edited to the new ranges. A pinned 4.17.1 becomes ^4.22.3 or ^5.0.0. The pins were there for a reason, even if the reason was only "this is what worked".
It can move a package to a version that resolves the advisory but isn't what you'd pick. The algorithm looks for a version of the top-level package whose dependency tree has no vulnerable version in it. That's not the same as "the latest" or "the sensible upgrade". The widely reported case was Create React App projects, where npm audit fix --force moved react-scripts to a version that couldn't build the app at all. Read the "Will install" lines before you trust them.
How to run npm audit fix --force safely
Treat it as an upgrade project with a known start point, not a command you run and hope.
1. Start clean, on a branch
Commit or stash everything first. The undo step below depends on package.json and package-lock.json being committed as they were before.
git status
git switch -c chore/npm-audit-force2. Read the dry run
--dry-run means, per the docs, that "you don't want npm to make any changes and that it should only report what it would have done":
npm audit fix --force --dry-runRead every Will install line. For each major jump, decide: do I use this package directly, and does its changelog mention anything I use? A test runner moving from 10 to 12 is a different risk from your web framework moving from 4 to 5.
If the list has one or two majors, skip --force and upgrade those packages on their own (next section). If it's a long list of dev tooling you don't touch directly, --force is reasonable.
3. Run it
npm audit fix --force
git diff package.jsonThe diff shows every range it changed. If it rewrote something you didn't expect, this is the moment to notice.
4. Test like a release
npm test
npm run buildThen use the app: sign in, the main flow, anything that takes money. Tests cover what you wrote tests for; a major version bump in a UI library or an auth SDK tends to break the parts nobody tested.
5. Check the audit again
npm audit --omit=dev--force sometimes leaves findings in place, because a parent package pins a vulnerable version exactly or no fix exists. What's left needs an override or a manual decision.
6. Merge, or throw the branch away
If it all works, commit package.json and package-lock.json together and merge. If it doesn't, delete the branch and upgrade one package at a time. Don't spend an evening fixing an app that --force broke in five places at once.
How to undo npm audit fix --force
If you committed before you ran it, undo is two commands:
git restore package.json package-lock.json
npm cinpm ci installs exactly what the restored lockfile says and removes anything else in node_modules, so you're back to the known state. If you hadn't committed, git stash before running the command would have given you the same way back; without either, npm audit fix --force has rewritten the two files and there's no record of what they said.
If you already committed the result and merged it, revert that commit, then npm ci.
The alternative: upgrade one package at a time
Most of the time the dry run shows one or two packages that need a major version, and the rest are dev tooling. Upgrade the ones that matter yourself:
npm install express@5
npm testThen run plain npm audit fix for everything that fits inside the ranges. You get the same result as --force for the packages you chose, and a diff you can explain. npm explain tells you which top-level package pulls in a vulnerable transitive one, so you know what to upgrade.
For a vulnerable transitive package whose parent hasn't released a fix, npm's overrides field forces a version without touching the parent. The walkthrough covers it.
When npm audit fix --force is the right call
- A fresh project you haven't built on yet. Nothing to break.
- The dry run shows only dev tooling you use through npm scripts, not through imports: test runners, linters, bundler plugins. Major bumps there usually mean a config change at most.
- A deliberate upgrade sprint, when you've blocked out the time and want npm to do the bulk edits before you fix what broke.
And when it isn't: the night before a launch, on main, because the install printed "11 high". Those findings are mostly in packages that never ship to production, and the right order starts with npm audit --omit=dev, not with --force. The one case that is an emergency is a package on CISA's Known Exploited Vulnerabilities catalog, and even then you upgrade that package, not everything.
npm audit fix --force not working
A few things that look like the flag failing:
- The count didn't move. The remaining findings have no fix, or a parent package pins the vulnerable version exactly.
npm audittells you which with itsNo fix availablelines;npm explain <package>shows the pin. npm audit fixis not available with pnpm or Yarn. Those tools have their own commands (pnpm audit --fix,yarn npm audit); npm's flag doesn't apply.- No
package-lock.json. npm needs the lockfile to audit and fix. Runnpm installonce to create it. The docs'--package-lock-onlyflag makes the fix "only use thepackage-lock.json, ignoringnode_modules", which is faster when you only want the files changed, not the install. - It installed something strange. See the
react-scriptscase above. Undo it and upgrade by hand.
Checklist
- Commit first, then branch.
npm audit fix --force --dry-runand read every "Will install" line.- One or two majors: upgrade them by name instead. A long list of dev tooling: go ahead.
- After running:
git diff package.json,npm test,npm run build, click through the app. - Re-run
npm audit --omit=devand deal with what's left. - Undo is
git restore package.json package-lock.json && npm ci. - Commit the two files together; install with
npm ciin CI.
Whatever you decide, commit the lockfile. It's what records the versions you tested, and it's what anything checking your repository for vulnerable packages reads. A free Tuvio scan of your GitHub repository, no account needed, reads the lockfile and reports known vulnerabilities in production dependencies, with the ones on CISA's exploited catalog listed first within their severity; the catalog behind it is refreshed weekly. A package.json without a lockfile isn't read. Coverage lists what is checked. Dependencies are one row of the vibe coding security checklist; the rest of it is worth the same evening.