How do I prevent npm:EBADPLATFORM in CI?

Check OS and CPU support before adopting packages with native binaries. Keep CI runner architecture explicit so x64 and arm64 jobs do not drift unexpectedly.

How can I manually validate npm:EBADPLATFORM?

Print the current platform with `node -p "process.platform + '/' + process.arch"`. Inspect package constraints: `npm view @ os cpu optionalDependencies`. If this is CI, confirm the runner architecture matches the one expected by the build or prebuilt binary.

npm ERR! code EBADPLATFORM

Fix it fast

Most likely: The package does not support your current operating system, CPU architecture, or both.

1. Confirm this is your error

npm ERR! code EBADPLATFORM
npm ERR! notsup Unsupported platform for package

2. Check the cause

node -p "process.platform + '/' + process.arch"
npm view <package>@<version> os cpu --json
npm config get platform
npm config get arch

3. Apply the safe fix

# Install on a supported OS/architecture, or choose a package version that supports this machine.
npm view <package>@<version> os cpu --json
npm install

# In CI, move the job to the runner architecture the package supports.

4. Verify it works

node -p "process.platform + '/' + process.arch"
npm install

Don't use unsafe shortcuts

Do not force platform or arch unless you are intentionally cross-building.
Do not treat this as a registry outage, npm already found the package metadata.
Do not delete the lockfile first if the real issue is an unsupported OS or CPU.

What Does Not Match This Runtime or Platform

npm returned EBADPLATFORM because the package does not support the current operating system, CPU architecture, or runtime combination.

Use a compatible runtime, platform, or published build

Use a package version that supports your current platform, or run the build on a supported OS and architecture.

If the failing dependency is optional, confirm your project can safely ignore it on this platform.

If the package must run here, follow its native-build instructions instead of treating this as a registry problem.

Why This Runtime or Platform Does Not Match

Usually this comes down to the package explicitly does not support your OS or CPU architecture, a native dependency only ships prebuilt binaries for some platforms, and the current one is not included, or an optional dependency became effectively required by your install or build process on an unsupported platform.

Prove the Runtime and Published Build Now Line Up

The reported process.platform and process.arch match a platform listed as supported by the package.

Re-run the original install on a supported platform, or after choosing a compatible version, and confirm EBADPLATFORM is gone.

Check runtime, platform, and index source

Print the current platform with node -p "process.platform + '/' + process.arch".

Inspect package constraints:npm view <pkg>@<version> os cpu optionalDependencies

If this is CI, confirm the runner architecture matches the one expected by the build or prebuilt binary.

How npm evaluates OS and CPU compatibility

Packages can declare supported os and cpu values, and native dependencies may only publish binaries for certain platforms. When the current machine does not match those constraints, npm skips optional packages or fails with EBADPLATFORM.

Prevent It From Coming Back

To prevent this, check OS and CPU support before adopting packages with native binaries, and keep CI runner architecture explicit so x64 and arm64 jobs do not drift unexpectedly.