neon-bindings/neon · error

Failed to load N-API symbols

Error message

Failed to load N-API symbols

What it means

`setup` is the one-time initializer that resolves every Node-API symbol from the host process via libloading. The `.expect` fires when `load` returns an Err — typically a `libloading::Error` from failing to resolve a symbol or (on Windows) from `Library::this()` — meaning the runtime does not provide the N-API symbols the compiled Neon feature set requires.

Solutions

1. Use a Node.js runtime that provides all symbols for the compiled napi feature level
2. Rebuild the addon with a lower napi-* feature (e.g. napi-6 instead of napi-8) for older runtimes
3. Load the addon only via Node's require()/import, never dlopen from foreign processes
4. On Windows, confirm the host process exports the N-API symbols (plain Node or Electron with N-API support)

Example fix

Match the neon napi-* cargo feature to the target Node runtime's Node-API version (lower the feature to napi-6 or napi-4 for older runtimes) and load the addon through require() in Node.

When it happens

Trigger: First use of any Neon API after module load: `setup(env)` calls `load(env)` exactly once (via `Once`), and panics if symbol loading fails — e.g. a required napi symbol is missing from the host or the host library cannot be opened on Windows.

Common situations: Addon built with napi-6/8 features loaded into a Node version lacking those symbols; loading the .node file from a non-Node process; Windows host library resolution failures; mismatched Node runtime in Electron/embedded setups.

AI-assisted analysis of neon-bindings/neon@38960e4381 (2026-09-13). Data as JSON: /api/errors/0df61ccefe5cd0fc. Report an issue: GitHub.

Appendix: source

Thrown at crates/neon/src/sys/mod.rs:137

/// Loads Node-API symbols from the host process.
///
/// Must be called at least once before using any functions in bindings or
/// they will panic.
///
/// # Safety
/// `env` must be a valid `napi_env` for the current thread
pub unsafe fn setup(env: Env) {
    SETUP.call_once(|| load(env).expect("Failed to load N-API symbols"));
}

View on GitHub (pinned to 38960e4381)