{"record":{"id":"802852e93b6d1d7f","repo":"neon-bindings/neon","slug":"node-api-symbol-has-not-been-loaded","errorCode":null,"errorMessage":"Node-API symbol has not been loaded","messagePattern":"Node-API symbol has not been loaded","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/neon/src/sys/bindings/mod.rs","lineNumber":123,"sourceCode":"/// pub(crate) unsafe fn get_undefined(env: Env, result: *mut Value) -> Status {\n///     (NAPI.get_undefined)(env, result)\n/// }\n/// ```\nmacro_rules! generate {\n    (#[$extern_attr:meta] extern \"C\" {\n        $($(#[$attr:meta])? fn $name:ident($($param:ident: $ptype:ty$(,)?)*)$( -> $rtype:ty)?;)+\n    }) => {\n        struct Napi {\n            $(\n                $name: unsafe extern \"C\" fn(\n                    $($param: $ptype,)*\n                )$( -> $rtype)*,\n            )*\n        }\n\n        #[inline(never)]\n        fn panic_load<T>() -> T {\n            panic!(\"Node-API symbol has not been loaded\")\n        }\n\n        static mut NAPI: Napi = {\n            $(\n                unsafe extern \"C\" fn $name($(_: $ptype,)*)$( -> $rtype)* {\n                    panic_load()\n                }\n            )*\n\n            Napi {\n                $(\n                    $name,\n                )*\n            }\n        };\n\n        pub(super) unsafe fn load(host: &libloading::Library) {\n            let print_warn = |err| eprintln!(\"WARN: {}\", err);","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/neon-bindings/neon/blob/38960e4381d9ad13b551cdf2d261f609167c9bc2/crates/neon/src/sys/bindings/mod.rs#L105-L141","documentation":"Neon's generated `sys::bindings` module declares stub `extern \"C\"` functions for every Node-API symbol; each stub panics with this message when called. The real symbols are only wired up at module load time by the generated registration code. Hitting a stub means the addon was loaded without its Node-API symbol table being initialized — the function you called was never resolved.","triggerScenarios":"Calling a Neon API whose backing Node-API symbol was never registered — commonly because the binary was built/run as a plain executable or test instead of being loaded by Node as a native module; using a symbol gated behind a newer `napi-X` feature flag that wasn't enabled; custom `#[node_api]`/sys usage before `init` ran.","commonSituations":"Running Neon code in `cargo test` unit tests or a `main.rs` binary where the Node module never loads; forgetting the `napi-6`/`napi-8` cargo feature while calling an API that requires it; linking the addon into a non-Node host that skips Neon's registration step.","solutions":["Load the addon through Node (require/import the built `.node` file) so Neon's symbol registration runs; don't call Neon code from a standalone binary or plain unit test — use integration tests via Node instead.","Enable the required cargo feature (e.g. `neon = { version = \"0.10\", features = [\"napi-8\"] }`) for the Node-API functions you use, then rebuild.","Ensure `neon::setup()`/generated registration is invoked exactly once at module load and wasn't removed or cfg'd out.","Rebuild the addon after changing neon versions so the generated symbol table matches the linked runtime."],"exampleFix":"// before\n// Cargo.toml\nneon = \"0.10\" // missing feature\n// code uses napi-8 APIs -> symbol stub panics\n\n// after\n// Cargo.toml\nneon = { version = \"0.10\", features = [\"napi-8\"] }","handlingStrategy":"validation","validationCode":"// verify the addon loads through Node before exercising APIs\nnode -e \"require('./index.node'); console.log('symbols loaded')\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only call Neon code from within a Node-loaded native module — use Node-run integration tests, not cargo unit tests","Enable the napi-X cargo feature matching the APIs you call","Keep neon registration code intact and called once at load","Rebuild the addon whenever neon or feature flags change"],"tags":["rust","neon","node-api","linking"],"backgroundTag":"missing-dependency","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"}