syncpack "version mismatch" - Fix Dependency Drift in CI

syncpack enforces that a shared dependency uses one consistent version across every workspace package. Its CI check fails when packages pin the same dependency to different ranges - version drift that causes duplicate installs and subtle bugs.

What this error means

A syncpack list-mismatches (or lint) step fails listing a dependency that appears at different versions across packages. Deterministic for the current package.json files.

syncpack output

✘ react
    ^18.2.0  @acme/web
    ^18.3.1  @acme/admin
    ^17.0.2  @acme/legacy
  (versions must match across the workspace)

Common causes

Same dependency pinned at different versions

Different packages declare different ranges for one dependency, so syncpack’s "same range across the workspace" policy fails.

No version group / catalog enforcing alignment

Without a syncpack version group (or a pnpm catalog) centralizing the version, drift creeps in package-by-package.

How to fix it

Fix mismatches automatically

Let syncpack rewrite package.json files to the chosen version, then commit.

Terminal

npx syncpack list-mismatches      # show the drift
npx syncpack fix-mismatches       # align them
git add . && git commit -m "align dependency versions"

Enforce alignment going forward

Add a .syncpackrc versionGroup (or semverGroup) pinning the policy.
Centralize shared versions via a pnpm catalog so packages reference one source.
Run syncpack list-mismatches as a required PR check.

How to prevent it

Run syncpack list-mismatches as a CI gate to block drift.
Centralize shared versions (syncpack version groups or pnpm catalogs).
Use syncpack fix-mismatches to realign before merging dependency bumps.