Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

bcrypt_lib.node: invalid ELF header inside a Docker container

ErrorError: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF header

Short 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.

  • Applies to bcrypt 6, Node.js 22, Docker 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 {} \;'
  2. 2Match what you see, then jump to its fix

    1. 1file prints Mach-O (macOS) or PE32 (Windows) for bcrypt_lib.nodeThe host node_modules folder was copied into the imageFix
    2. 2The 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. 3node_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

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" Dockerfile

2Fix

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

Did this fix it?

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-container

2Fix

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-image

3Verify

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

Did this fix it?

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 bcrypt

2Fix

Rebuild the package on the system that will run it. Use a bcrypt version that supports your Node.js version.

npm rebuild bcrypt

3Verify

Load the module.

node -e "require('bcrypt'); console.log('ok')"

Confirmed by docs.npmjs.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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