Maaz Zindani

Loading the index…

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

A native Node.js module fails on AWS Lambda with invalid ELF header

Errorinvalid ELF header

Short answer

Lambda loads native addons on Linux, so a .node file built on macOS or Windows is not a valid Linux ELF file there. The file must also match the function's CPU architecture, x86_64 by default. Check what kind of file the addon is, then rebuild it for Linux and the right architecture, in the package or in the layer.

  • Applies to AWS Lambda nodejs22.x (Amazon Linux 2023), npm 11, AWS SAM CLI
  • 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 each compiled addon in your package is. Run it in the folder you zip. Mach-O (macOS) or PE32 (Windows) means the wrong operating system. ELF means Linux, so then compare the CPU it names with your function's architecture.

    find node_modules -name "*.node" -exec file {} \;
  2. 2Match what you see, then jump to its fix

    1. 1file prints Mach-O or PE32 for the .node file, and the error path starts with /var/taskThe package was installed on macOS or Windows and zipped as it wasFix
    2. 2file prints ELF, yet for another processor than the function runs on (for example ARM aarch64 for a function set to x86_64)The addon is Linux, but built for a different CPU than the functionFix
    3. 3The error path starts with /opt/nodejs/node_modules instead of /var/taskThe native module comes from a layer that was built somewhere elseFix

What does the error look like?

  • invalid ELF header
  • Error: /var/task/node_modules/<package>/build/Release/<name>.node: invalid ELF header

Cause 1 of 3

The package was installed on macOS or Windows and zipped as it was

1Check

npm installs the compiled addon that fits the machine it runs on. A deployment zip made from that node_modules carries the macOS or Windows file to Lambda, whose Node.js runtimes run on Amazon Linux 2023. Lambda unpacks a .zip package into /var/task.

uname -s
find node_modules -name "*.node" -exec file {} \;

2Fix

Build the package for Linux. If the module ships prebuilt binaries per platform, tell npm which target to install for. If it compiles on install, build inside a Lambda-like container with AWS SAM.

# prebuilt binaries: reinstall for Linux and the function's CPU (x64 for x86_64)
rm -rf node_modules
npm install --os=linux --cpu=x64

# compiled on install: build in a Lambda-like Docker container
sam build --use-container

3Verify

The same file check now prints ELF for every addon.

find node_modules -name "*.node" -exec file {} \;

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

The addon is Linux, but built for a different CPU than the function

1Check

A function runs on either x86_64 or arm64, and x86_64 is the default. The code in the package must be compatible with the architecture of the function. A package built on an ARM Linux machine, such as an ARM CI runner, is an arm64 build. The load error can read differently in this case, so trust the file check. Open the function in the console and read Architecture under Runtime settings on the Code tab.

uname -m
find node_modules -name "*.node" -exec file {} \;

2Fix

Make the two match. Either rebuild the package for the function's architecture, or switch the function to the architecture the package was built for, in Runtime settings, after checking that every layer and extension supports it too.

# rebuild for an arm64 function
rm -rf node_modules
npm install --os=linux --cpu=arm64

3Verify

Redeploy and invoke the function. The module loads without the error.

find node_modules -name "*.node" -exec file {} \;

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

The native module comes from a layer that was built somewhere else

1Check

Lambda loads layer content into /opt. The architecture guide tells you to check every layer of a function for compatibility with its architecture. A layer zipped from a laptop carries the laptop's binaries.

unzip -o layer.zip -d /tmp/layer-check
find /tmp/layer-check -name "*.node" -exec file {} \;

2Fix

Build the layer for Linux and the function's architecture, with the dependencies under nodejs/node_modules, and publish it as a new layer version. If the module compiles on install, define the layer in your SAM template and build it with sam build --use-container, which builds functions and layers.

mkdir -p nodejs && cp package.json nodejs/
cd nodejs && npm install --os=linux --cpu=x64 && cd ..
zip -r layer.zip nodejs

3Verify

Run the file check on the new zip. Every addon shows as an ELF file for the right CPU, then attach the new version and invoke the function.

unzip -o layer.zip -d /tmp/layer-check
find /tmp/layer-check -name "*.node" -exec file {} \;

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Build the deployment package in CI on Linux, or with sam build --use-container, and never zip a laptop's node_modules.
  • Write the function's architecture down next to the build step, and pass the matching --cpu value.
  • Add the find and file check to the pipeline, and fail the build when an addon is not ELF.
  • Prefer packages that offer a pure JavaScript or WebAssembly build when you can, because they have no CPU or operating system to match.

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

Servers

Apache has a certificate, but https:// does not open

No line with :443 in the output of ss -ltnp

HTTPS needs four things at once: mod_ssl loaded, Apache listening on 443, a virtual host on 443 with SSLEngine on, and a firewall that lets 443 in.

4 causes, each with a fix

Servers

AWS CLI says you must specify a region

You must specify a region. You can also configure your region by running "aws configure".

The AWS CLI sends every request to one region and has none to use.

4 causes, each with a fix

Next step

Want this handled for good?

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