Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node reports that no native build was found for your platform

ErrorError: No native build was found for platform=win32 arch=x64 runtime=node abi=108 uv=1 libc=glibc node=18.7.0

Short answer

The package loads its native .node file through node-gyp-build. That library looks in build/Release, build/Debug and a prebuilds folder, and throws when nothing matches your platform, architecture, Node ABI and libc. Read the values in the message, then reinstall on this machine, force a local build, or fix the override.

  • Applies to Node.js 18 to 24, Windows 11, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the platform, arch, abi and libc in the message, then compare them with the machine and see which prebuilds the package ships.

    node -p "process.platform + ' ' + process.arch + ' ' + process.versions.modules"
    ls node_modules/<package>/prebuilds
  2. 2Match what you see, then jump to its fix

    1. 1The message names a platform or arch other than the machine you run on, or the folder came from a copy or a Docker layernode_modules was installed on a different systemFix
    2. 2The prebuilds folder has no folder for your platform-arch, or the files do not match the abi in the messageThe package ships no prebuild for your platform, architecture or Node versionFix
    3. 3libc=glibc or libc=musl in the message does not match the systemThe libc is detected wronglyFix
    4. 4PREBUILDS_ONLY, npm_config_platform or npm_config_arch is set in the shell or in CIAn environment variable hides or redirects the buildFix

What does the error look like?

  • Error: No native build was found for platform=win32 arch=x64 runtime=node abi=108 uv=1 libc=glibc node=18.7.0
  • loaded from: <path to the package>

Cause 1 of 4

node_modules was installed on a different system

1Check

node-gyp-build reads the platform and arch of the running process. Folders under prebuilds are named platform-arch, so a copied node_modules from another system has no match.

ls node_modules/<package>/prebuilds

2Fix

Delete node_modules and install on the system that will run the code. Never copy node_modules between systems.

rm -rf node_modules
npm ci

3Verify

Start the app, or load the module on its own.

node -e "require('<package>')"

Confirmed by github.com

Did this fix it?

Cause 2 of 4

The package ships no prebuild for your platform, architecture or Node version

1Check

The library picks a file by runtime, ABI, libc and similar tags. Without a match it throws. The README says you can force compiling with --build-from-source.

ls node_modules/<package>/prebuilds/*

2Fix

Reinstall the package and force a local build. This needs a compiler toolchain (see the node-gyp page) or use a package or Node version that ships a matching prebuild.

npm install --build-from-source

3Verify

A build/Release folder with a .node file exists and loads.

ls node_modules/<package>/build/Release

Confirmed by github.com

Did this fix it?

Cause 3 of 4

The libc is detected wrongly

1Check

The library reports musl on Alpine and glibc elsewhere unless the LIBC variable is set. A prebuild for the other libc is ignored.

echo "$LIBC"
ls node_modules/<package>/prebuilds/*

2Fix

Unset a wrong LIBC value, or set it to the libc of the system, then run again. The ARM_VERSION variable works the same way for ARM builds.

unset LIBC
# or set it explicitly, for example: export LIBC=musl

3Verify

The module loads.

node -e "require('<package>')"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 4 of 4

An environment variable hides or redirects the build

1Check

PREBUILDS_ONLY makes the library skip build/Release and build/Debug. npm_config_platform and npm_config_arch replace the real platform and arch in the lookup.

env | grep -E "PREBUILDS_ONLY|npm_config_(platform|arch)|_PREBUILD"

2Fix

Unset the variables that do not belong, and reinstall.

unset PREBUILDS_ONLY npm_config_platform npm_config_arch
npm ci

3Verify

The module loads without the variables.

node -e "require('<package>')"

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Build and run on the same system type, or run npm ci inside the target image.
  • Add node_modules to .dockerignore and .gitignore so another system's files never travel.
  • Test a Node.js upgrade in CI before it reaches production, since the ABI number changes with it.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.