Build fails in CI on a missing platform-specific package that is not in my dependencies — works fine locally

The error message is unusually honest — it really is a package manager problem, and understanding the mechanism tells you which fix is right for your situation.

The mechanism. Tools with native components ship a separate prebuilt package per platform and architecture, and depend on all of them as optional dependencies. At install time the manager is supposed to evaluate each one's platform constraints and install only the matching one. That is why you have never heard of the package: it is a transitive optional dependency, correctly invisible until it goes wrong.

The failure comes from how optional dependencies get recorded in the lockfile. If the lockfile was generated on one platform, it can end up recording only that platform's variant — so installing from it on a different platform produces a tree with no matching native package, and the build dies looking for one. Your machine and your CI runner being different platforms is exactly the setup that exposes it.

A related shape: an interrupted or partial install leaves the optional entries missing, and every subsequent install from that lockfile is missing them too, permanently, because the lockfile is now the source of truth.

The fix depends on what you can change:

If you can regenerate the lockfile — do that, and commit it. Delete the lockfile and the installed modules locally, install fresh, and check whether the platform variants for all your targets appear. On a recent package manager version this produces a lockfile that carries every optional variant, and CI then resolves the right one. This is the actual fix.

Upgrade the package manager first. This was a known defect and it has been addressed; a CI runner pinned to an older version will keep reproducing it against a perfectly good lockfile. Check the version in CI specifically — it is frequently much older than the one on your machine, and that alone explains "works locally".

If you need it working in the next ten minutes, add the platform-specific package your CI needs as an explicit optional dependency of your project. Ugly, effective, and it does not break other platforms because the constraint still applies. Leave a comment saying why, or somebody deletes it in six months and this comes back.

What not to do: delete the lockfile in CI. The error message suggests it and it will make the build pass, and it removes the entire guarantee the lockfile exists to provide — CI now installs whatever is newest, and you have converted a reproducible build into one that can break overnight for unrelated reasons. If you take that path you have swapped this problem for a worse and less obvious one.

The general lesson worth taking away: if a build works on one machine and not another, the difference is in the environment, and platform-specific native packages are one of the few places where a lockfile — the thing meant to eliminate environment differences — can itself be the difference. Make CI and local as similar as you reasonably can, and pin the package manager version alongside the runtime version.

Worth checking whether your CI caches the installed modules directory between runs, because that turns this into an intermittent that survives fixes.

A cached tree from before the fix gets restored, the install step sees everything present and does nothing, and the build fails identically after you have corrected the lockfile. Then it passes on a runner with a cold cache, and you conclude the fix was flaky.

Cache the package manager's download store rather than the installed tree, which is the recommended pattern anyway, and bust the cache on lockfile changes. If you are debugging this right now, clear the cache before you evaluate whether a fix worked.

If your local machine and your CI runner have different architectures — which is common now with ARM laptops and x86 runners — this bites much harder, and it will bite you again with other native dependencies.

The durable fix is to make the build environment identical rather than similar: build in a container, with the same base image locally and in CI. Then the lockfile is generated and consumed on the same platform and the whole class of problem disappears.

More setup than editing a dependency list, and it also solves the next four versions of this question.

Small operational point: when you regenerate the lockfile, review the diff rather than committing it blind.

A regenerated lockfile can quietly bump a lot of transitive versions if any of your ranges are loose, so you fix the platform problem and simultaneously ship fifty unrelated dependency updates in the same commit. When something breaks next week, that commit is a very unpleasant thing to bisect into.

If the diff is huge, that is itself worth knowing about.