This error occurs when Node.js tries to load a native addon compiled for glibc on Alpine Linux (which uses musl). The fix involves rebuilding native modules with Alpine's build tools or switching to a glibc-based Docker image.
This error occurs when Node.js tries to load a native addon (compiled C++ module) at runtime, but the .node binary file doesn't exist in the expected location. Native modules are compiled during npm install using node-gyp, which invokes the system's C++ compiler to build platform-specific binaries. The missing file indicates either that the compilation failed silently, the module wasn't compiled for your system architecture, or—most commonly in Docker environments—the module was compiled for a different C standard library (glibc on your development machine vs musl on Alpine Linux containers). This mismatch is particularly problematic because native binaries are not portable across different libc implementations; a binary compiled against glibc will fail to load on a musl system, and vice versa.
First, attempt to rebuild the native modules in your current environment:
npm rebuildIf targeting a specific problematic package:
npm rebuild package-name --build-from-sourceIf this succeeds, the issue may have been incomplete compilation. If it still fails, the root cause is likely environmental mismatch (Docker-related).
Delete cached modules and reinstall from scratch:
rm -rf node_modules package-lock.json
npm cache clean --force
npm installOr use the more reliable clean-install command:
npm ciThis ensures npm doesn't use cached prebuilt binaries.
If running in a Docker container with Alpine Linux, the C compiler toolchain isn't included by default. Add build tools before installing dependencies:
FROM node:alpine
# Install build dependencies
RUN apk add --no-cache python3 make g++
WORKDIR /app
COPY package*.json ./
# Now npm install will rebuild native modules against musl
RUN npm install
COPY . .
CMD ["node", "index.js"]Use --virtual to tag and later remove build dependencies:
RUN apk add --no-cache --virtual .gyp python3 make g++ \
&& npm install \
&& apk del .gypBuild native modules in one stage with full build tools, then copy only the compiled binaries to a final minimal image:
# Builder stage - includes compilation tools
FROM node:alpine as builder
RUN apk add --no-cache python3 make g++
WORKDIR /app
COPY package*.json ./
RUN npm install
# Final stage - minimal runtime image
FROM node:alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
COPY . .
CMD ["node", "index.js"]This reduces final image size while ensuring native modules are compiled for musl.
The simplest solution is to avoid Alpine entirely and use the standard Node image based on Debian:
# Using Debian-based image instead of Alpine
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "index.js"]Node images ending in -slim are still small (~200MB) but use glibc, matching most pre-built native module binaries.
The core issue is that Alpine Linux uses musl libc while most development machines and pre-built binaries use glibc (GNU C Library). These are incompatible C standard library implementations—they have different ABIs, memory allocation strategies, and system call interfaces.
A .node file (native addon) compiled against glibc contains hardcoded references to glibc functions that don't exist in musl's namespace. When Node.js tries to dynamically load this binary into a musl-based process, the dynamic linker fails because it can't resolve those symbols.
The npm package detect-libc can programmatically identify which libc is present. For production deployments, Node.js official documentation recommends glibc-based images for Tier 1 support; musl on Alpine is experimental.
Some packages like node-sass and bcrypt are notorious for musl incompatibility; check GitHub issues before selecting Alpine for projects with heavy native dependencies.
npm error code E401 npm error Incorrect or missing password.
How to fix 'E401 Unable to authenticate' errors with npm private registries
npm ERR! code EAI_NODATA npm ERR! errno EAI_NODATA npm ERR! getaddrinfo EAI_NODATA registry.npmjs.org
How to fix "npm ERR! code EAI_NODATA - getaddrinfo EAI_NODATA"
npm ERR! code EMPTYPACKAGE npm ERR! Package contains no files
How to fix 'npm ERR! code EMPTYPACKAGE' - Package contains no files
npm notice access token expired or revoked. Please try logging in again.
Token has expired - npm authentication failure
npm ERR! code EAI_AGAIN
How to fix "EAI_AGAIN" in npm