{"record":{"id":"0df61ccefe5cd0fc","repo":"neon-bindings/neon","slug":"failed-to-load-n-api-symbols","errorCode":null,"errorMessage":"Failed to load N-API symbols","messagePattern":"Failed to load N-API symbols","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/neon/src/sys/mod.rs","lineNumber":137,"sourceCode":"/// Loads Node-API symbols from the host process.\n///\n/// Must be called at least once before using any functions in bindings or\n/// they will panic.\n///\n/// # Safety\n/// `env` must be a valid `napi_env` for the current thread\npub unsafe fn setup(env: Env) {\n    SETUP.call_once(|| load(env).expect(\"Failed to load N-API symbols\"));\n}","sourceCodeStart":119,"sourceCodeEnd":139,"githubUrl":"https://github.com/neon-bindings/neon/blob/38960e4381d9ad13b551cdf2d261f609167c9bc2/crates/neon/src/sys/mod.rs#L119-L139","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a Node.js runtime that provides all symbols for the compiled napi feature level","Rebuild the addon with a lower napi-* feature (e.g. napi-6 instead of napi-8) for older runtimes","Load the addon only via Node's require()/import, never dlopen from foreign processes","On Windows, confirm the host process exports the N-API symbols (plain Node or Electron with N-API support)"],"exampleFix":"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.","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Test addon loading against all supported Node runtimes in CI","Document the minimum Node-API version implied by the chosen neon features"],"tags":[],"backgroundTag":null,"analyzedSha":"38960e4381d9ad13b551cdf2d261f609167c9bc2","analyzedAt":"2026-09-13T09:05:33.640Z","contentChangedAt":"2026-09-13T09:05:33.640Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}