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 ERR! code E401 npm ERR! 401 Unauthorized - Token has expired
Token has expired - npm authentication failure
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 ERR! code EWORKSPACEMISSING npm ERR! Workspace does not exist: packages/missing
How to fix "npm ERR! code EWORKSPACEMISSING - Workspace does not exist" error
npm ERR! code EADDRNOTAVAIL npm ERR! errno EADDRNOTAVAIL npm ERR! Address not available
How to fix "npm ERR! code EADDRNOTAVAIL - Address not available" error