How to fix npm ERR! In file included from ../node_modules/node-addon-api/napi.h in npm

npmINTERMEDIATEHIGHUpdated Dec 5, 2025· 131 views

This error occurs during native module compilation when the node-addon-api headers can't be found or have compatibility issues. Usually caused by missing include paths or version mismatches.

Quick fix

Fixes npm ERR! In file included from ../node_modules/node-addon-api/napi.h

npm update node-addon-api

# Or install latest
npm install node-addon-api@latest
  1. Update node-addon-api
  2. Download Node.js headers
  3. Install build tools
  4. Clean reinstall
npm — error
npm update node-addon-api
# Or install latest
npm install node-addon-api@latest
npm ERR! In file included from ../node_modules/node-addon-api/napi.h

What this error means

The error referencing `node-addon-api/napi.h` indicates a problem compiling a native module that uses Node-API (formerly N-API). Node-API is a stable ABI for building native addons that work across Node.js versions. This error typically means: - The C++ compiler can't find the napi.h header file - There's a version mismatch between node-addon-api and Node.js - The binding.gyp file has incorrect include paths - Node.js headers weren't downloaded properly The error message usually continues with the specific compilation error (missing file, type error, etc.).

Typical symptoms

  • Compilation error mentioning node-addon-api/napi.h
  • Build fails during npm install of native module
  • Error about 'No such file or directory' for napi.h
  • Type conversion errors in napi code

Common causes

  1. node-addon-api version incompatible with Node.js version
  2. Missing node-addon-api dependency
  3. Incorrect include paths in binding.gyp
  4. Node.js headers not downloaded by node-gyp
  5. Build tools not properly installed

How to fix "npm ERR! In file included from ../node_modules/node-addon-api/napi.h"

1Update node-addon-api

Ensure you have a compatible version:

bash
npm update node-addon-api

# Or install latest
npm install node-addon-api@latest

For Node.js 20.12+, you need node-addon-api 7.1.0 or later.

2Download Node.js headers

node-gyp needs Node.js header files:

bash
# Remove old headers
rm -rf ~/.node-gyp

# Download fresh headers
node-gyp install

# Rebuild
npm rebuild
3Install build tools

Ensure you have C++ compilation tools:

Linux:

bash
sudo apt-get install build-essential python3

macOS:

bash
xcode-select --install

Windows:

bash
npm install --global windows-build-tools
4Clean reinstall

Do a complete clean install:

bash
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
5Check for specific compilation errors

Look at the full error message. Common issues:

"napi.h: No such file or directory": node-addon-api not installed or binding.gyp has wrong include path.

Type conversion errors: Usually version mismatch. Update node-addon-api.

"nogc_finalize" errors (Node.js 20.12+): Update to node-addon-api 7.1.0+.

Advanced notes

For package maintainers: Ensure binding.gyp includes node-addon-api:

json
{
  "targets": [{
    "target_name": "addon",
    "include_dirs": [
      "<!@(node -p \"require('node-addon-api').include\")"
    ],
    "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]
  }]
}

Node.js 20.12+ breaking changes: The Node-API introduced changes that require node-addon-api 7.1.0+. If you can't upgrade the package, you may need to use an older Node.js version temporarily.

NAPI_VERSION: Some packages require specific NAPI versions. Check the package documentation for requirements.

Prebuild: For packages you maintain, consider using prebuild to ship precompiled binaries and avoid end-user compilation:

bash
npm install --save-dev prebuild prebuild-install

Frequently asked questions

What does "npm ERR! In file included from ../node_modules/node-addon-api/napi.h" mean?
h indicates a problem compiling a native module that uses Node-API (formerly N-API). js versions. ).
How do I fix "npm ERR! In file included from ../node_modules/node-addon-api/napi.h"?
This error occurs during native module compilation when the node-addon-api headers can't be found or have compatibility issues. Usually caused by missing include paths or version mismatches.
What causes "npm ERR! In file included from ../node_modules/node-addon-api/napi.h"?
node-addon-api version incompatible with Node.js version Missing node-addon-api dependency Incorrect include paths in binding.gyp
Is the "npm ERR! In file included from ../node_modules/node-addon-api/napi.h" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading