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.
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.).
Ensure you have a compatible version:
npm update node-addon-api
# Or install latest
npm install node-addon-api@latestFor Node.js 20.12+, you need node-addon-api 7.1.0 or later.
node-gyp needs Node.js header files:
# Remove old headers
rm -rf ~/.node-gyp
# Download fresh headers
node-gyp install
# Rebuild
npm rebuildEnsure you have C++ compilation tools:
Linux:
sudo apt-get install build-essential python3macOS:
xcode-select --installWindows:
npm install --global windows-build-toolsDo a complete clean install:
rm -rf node_modules package-lock.json
npm cache clean --force
npm installLook 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+.
For package maintainers: Ensure binding.gyp includes node-addon-api:
{
"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:
npm install --save-dev prebuild prebuild-installnpm 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