Docs / Checks / Upgrade/Feature

Updated July 31, 2026 · Upgrade/Feature · Medium severity

Your web framework is a major version or two behind

Seen in 23 of 450 scanned projects (5%). Based on automated dependency scans across 450 audited production repositories.

Common stacks: npm package.json framework ORM CI

How to tell you have it

Why it matters

Frameworks stop patching old majors once a new one ships. Once your installed version falls out of the support window, security fixes, CVE patches, and even routine bug fixes simply never reach you. You are stuck running code the maintainers no longer consider safe, and every month that passes the gap between what you run and what is actually supported gets wider.

Version skew inside your own dependency tree causes silent breakage. A first-party plugin built against next major of the core framework can install fine alongside an older core, then fail at runtime in ways that never show up in a diff or a code review, only in production logs. These are some of the hardest bugs to trace back to their real cause.

The longer an upgrade is deferred, the more it costs to do. Two years of deferred majors means the migration guide is now three migration guides stacked on top of each other, breaking changes compound, and nobody on the team remembers why a workaround was added. What would have been a one-day bump becomes a multi-week rewrite with a much higher chance of regressions.

Old, unsupported versions are a known target. Automated scanners and bots specifically fingerprint outdated framework versions from response headers, bundle signatures, and error pages, then check them against public advisory databases. Being visibly behind is itself a signal that invites more scrutiny than a project on a current, patched release.

How Heygents detects it

How to fix it

1. Get the full picture before touching anything Run outdated and audit together so you see both the version gap and whether any of it is a known vulnerability, not just a stale number.
2. Lock in a safety net before upgrading Do not start a major bump without a test suite that actually exercises the app's critical paths. If coverage is thin, write smoke tests for the top user flows first, this is the difference between an upgrade and a gamble.
3. Upgrade one major at a time, never skip Jumping from major 2 to major 5 directly means debugging three sets of breaking changes at once with no way to isolate which one broke what. Land each major, run the suite, commit, then move to the next.
4. Replace deprecated auth helpers with the maintained package Old auth-helper packages are often superseded by an official successor with the same functionality but active patching. Swap the import, not just the version, since the API usually moves too.
5. Replace out-of-repo tarball pins with a real published version A dependency pinned to a GitHub tarball or commit hash instead of an npm-published version means your build is not reproducible and you cannot audit it with standard tooling. Find the equivalent published release and pin to that instead.
6. Set a scheduled dependency bump so drift never reaches two majors again A weekly or biweekly cron-driven check that opens a PR for outdated packages keeps the gap small enough that each bump is boring. This is cheaper than any single big-bang migration and it turns upgrades into routine maintenance instead of a project.

Get the full picture before touching anything

npm outdated
npm audit --omit=dev
npm view <framework> versions --json | tail -20

Lock in a safety net before upgrading

npm test -- --coverage
# if coverage is under ~40% on critical routes, add smoke tests first

Upgrade one major at a time, never skip

npm install <framework>@3 --save-exact
npm test && git commit -am "upgrade <framework> to v3"
npm install <framework>@4 --save-exact
npm test && git commit -am "upgrade <framework> to v4"

Replace deprecated auth helpers with the maintained package

npm uninstall @framework/auth-helpers-legacy
npm install @framework/ssr
// update imports across the codebase
// old: import { createClient } from '@framework/auth-helpers-legacy'
// new: import { createServerClient } from '@framework/ssr'

Replace out-of-repo tarball pins with a real published version

// package.json - before
"some-lib": "github:someuser/some-lib#a1b2c3d"

// after, pinned to a real published release
"some-lib": "4.2.1"

Set a scheduled dependency bump so drift never reaches two majors again

# crontab entry, runs every Monday at 6am
0 6 * * 1 cd /var/www/<app> && npm outdated --json > /tmp/outdated-report.json

Frequently asked questions

How many major versions behind is actually dangerous?

One major behind is normal and low risk if the version is still receiving patches. Two or more majors behind is where risk climbs sharply, since most frameworks stop backporting security fixes past one or two prior majors. Check the framework's own support policy page rather than guessing from the version number alone.

Can I skip straight to the latest major to save time?

You can, but debugging is much harder because multiple unrelated breaking changes land at once with no way to tell which change caused which failure. Upgrading one major at a time behind a passing test suite takes longer in wall-clock steps but is far more reliable and easier to roll back if something breaks.

What if the framework major bump breaks a plugin I depend on?

Check the plugin's own changelog and repo issues before upgrading the core, since plugin authors usually publish a compatible major within weeks of the core release. If no compatible version exists yet, either delay that specific plugin's usage behind a feature flag or find an actively maintained alternative before committing to the upgrade.

Is pinning an exact version instead of using a caret range safer?

Exact pinning prevents surprise minor or patch bumps from breaking a deploy, which is reasonable for production stability. The tradeoff is that nothing ever updates automatically, so you need a deliberate, scheduled process to review and bump pinned versions, otherwise exact pins quietly turn into years of drift.

Does an ORM or test toolchain years behind carry the same risk as the framework?

Yes, often more, since ORMs sit directly on top of your database connection and old versions can miss fixes for connection leaks, injection edge cases, or migration bugs. An outdated test toolchain is lower direct risk but slows every future upgrade, since flaky or incompatible test tooling makes teams avoid running the suite at all.