bcrypt_lib.node: invalid ELF header inside a Docker container
Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF headerShort answer
bcrypt is a compiled addon, so the file in node_modules only runs on the operating system it was installed on. An invalid ELF header means a binary built for macOS or Windows was loaded on Linux. Keep the host node_modules out of the image with .dockerignore and install inside the container.
Fix it fast
1Find out which cause you have
Ask the operating system what kind of file the addon is. Inside the container, a Mach-O or PE32 result confirms a host build was copied in.
docker run --rm my-image sh -c 'find /app/node_modules/bcrypt -name "*.node" -exec file {} \;'2Match what you see, then jump to its fix
- 1
file prints Mach-O (macOS) or PE32 (Windows) for bcrypt_lib.nodeThe host node_modules folder was copied into the imageFix - 2
The image runs fine alone, but fails when started with a volume mapping your project folderA bind mount hides the node_modules installed in the imageFix - 3
node_modules was installed on another system or before a Node.js upgrade, and you cannot simply reinstallThe addon was built for another platform or Node.js version and needs rebuildingFix
- 1
What does the error look like?
Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF header
Cause 1 of 3
The host node_modules folder was copied into the image
1Check
A COPY . . in the Dockerfile copies everything in the build context, including node_modules from your machine. The README says bcrypt ships prebuilt binaries per platform, so a folder installed on a Mac holds the Mac one. A .dockerignore keeps listed folders out of the context.
cat .dockerignore
grep -n "COPY" Dockerfile2Fix
Ignore node_modules in .dockerignore and run the install inside the image, after the package files are copied.
# .dockerignore
node_modules
# Dockerfile
FROM node:22
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .3Verify
Rebuild without the cache and run the same file check. It now reports an ELF 64-bit file.
docker build --no-cache -t my-image .
docker run --rm my-image node -e "require('bcrypt'); console.log('bcrypt ok')"Confirmed by docs.docker.com
Cause 2 of 3
A bind mount hides the node_modules installed in the image
1Check
A bind mount hides whatever the image had at that path. Mounting the whole project over /app replaces the container's Linux node_modules with the host's.
docker inspect --format '{{json .Mounts}}' my-container2Fix
Mount only the source folders you edit, so /app/node_modules stays the one from the image.
docker run --rm -p 3000:3000 -v "$PWD/src:/app/src" my-image3Verify
The container starts and loads bcrypt.
docker run --rm -v "$PWD/src:/app/src" my-image node -e "require(\"bcrypt\"); console.log(\"ok\")"Confirmed by docs.docker.com
Cause 3 of 3
The addon was built for another platform or Node.js version and needs rebuilding
1Check
npm rebuild runs the install scripts of a package again, which is the step that fetches or builds the addon for the current system. The bcrypt README lists which bcrypt versions fit which Node.js versions.
node --version
npm ls bcrypt2Fix
Rebuild the package on the system that will run it. Use a bcrypt version that supports your Node.js version.
npm rebuild bcrypt3Verify
Load the module.
node -e "require('bcrypt'); console.log('ok')"Confirmed by docs.npmjs.com
How do I stop it coming back?
- Keep node_modules in both .gitignore and .dockerignore, and never COPY it into an image.
- Run npm ci inside the Dockerfile, so the install matches the base image's operating system and CPU.
- In development, mount only source code folders into the container.
- Check the bcrypt README for the Node.js versions it supports before upgrading Node.js.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Servers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
cdk deploy fails in a GitLab job with spawnSync docker ENOENT
code: 'ENOENT'
ENOENT means the operating system found no docker program to run.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
Node.js app says Cannot find module only when it runs under Docker Compose
The same image starts fine with docker run but fails with docker compose up
The image installed node_modules, but a Compose volume mounted over the app folder hides them.
3 causes, each with a fixServers
EACCES permission denied when a container creates node_modules/.cache
The dev server exits right after start when node_modules is a Compose volume
The container user cannot write inside node_modules because the folder is owned by root.
2 causes, each with a fixServers
The Next.js container starts with docker run but Compose fails with next: not found
/bin/sh: 1: next: not found
The shell cannot find the next binary.
3 causes, each with a fix