{"record":{"id":"667df12187f81b73","repo":"denoland/deno","slug":"initialize-libloading-failed","errorCode":null,"errorMessage":"Initialize libloading failed {}","messagePattern":"Initialize libloading failed (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"libs/napi_sys/src/lib.rs","lineNumber":125,"sourceCode":"pub use types::*;\n\n#[cfg(windows)]\nstatic SETUP: Once = Once::new();\n\n/// Loads N-API symbols from host process.\n/// Must be called at least once before using any functions in bindings or\n/// they will panic.\n///\n/// # Safety\n///\n/// `env` must be a valid `napi_env` for the current thread.\n#[cfg(windows)]\npub unsafe fn setup() {\n  SETUP.call_once(|| {\n    let host = match libloading::os::windows::Library::this() {\n      Ok(lib) => lib.into(),\n      Err(err) => {\n        panic!(\"Initialize libloading failed {}\", err);\n      }\n    };\n\n    // SAFETY: Once ensures single-threaded init; host is a valid library handle.\n    unsafe {\n      if let Err(err) = functions::load(&host) {\n        panic!(\"{}\", err);\n      }\n    }\n  });\n}\n","sourceCodeStart":107,"sourceCodeEnd":137,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/libs/napi_sys/src/lib.rs#L107-L137","documentation":"On Windows, the napi_sys bindings resolve N-API function pointers from the host module at runtime. setup() must run once before any binding is used: it obtains the current module handle via libloading::os::windows::Library::this() and panics if the handle cannot be acquired, because no napi function pointer could be resolved afterwards.","triggerScenarios":"Calling unsafe napi_sys::setup() on Windows in a host where Library::this() fails to return the current DLL handle: the napi glue is statically linked into an executable, loaded through a custom loader that does not register a module handle, or the HMODULE context is otherwise unavailable.","commonSituations":"Embedding Deno's napi compatibility layer into a non-Deno host on Windows; test harnesses that load the module in unusual ways; packaging changes (static vs dynamic linking) that leave the module without a resolvable handle.","solutions":["Compile and load the napi glue as a real DLL on Windows so the current module handle exists","Call napi_sys::setup() exactly once during module/thread initialization before touching any binding","If you control the host, load the library with LoadLibrary instead of static linking so libloading can find the handle","Wrap setup in std::panic::catch_unwind during bring-up to convert the abort into a reportable startup error"],"exampleFix":"// before\nunsafe { napi_sys::setup(); } // panics: Initialize libloading failed ...\n\n// after\nlet ok = std::panic::catch_unwind(|| unsafe { napi_sys::setup() });\nif ok.is_err() {\n  return Err(\"napi_sys setup failed: host module handle unavailable\");\n}","handlingStrategy":"validation","validationCode":"// Windows-only pre-check mirroring what setup() needs to succeed\n#[cfg(windows)]\nfn can_resolve_host_module() -> bool {\n  libloading::os::windows::Library::this().is_ok()\n}\n\n// run before any napi work\nif cfg!(windows) && !can_resolve_host_module() {\n  return Err(\"napi unavailable: host module handle cannot be resolved\");\n}","typeGuard":null,"tryCatchPattern":"let setup = std::panic::catch_unwind(|| unsafe { napi_sys::setup() });\nif setup.is_err() {\n  // report a startup error instead of aborting the host process\n}","preventionTips":["Always run napi_sys::setup() during deterministic initialization, before any binding can be reached","Load the napi glue as a DLL on Windows; never statically link it into an executable","Add a startup smoke test that calls setup() so packaging regressions surface immediately"],"tags":["napi","windows","ffi","native-modules","panic"],"backgroundTag":"native-library-load-failure","analyzedSha":"9ad36f7a2cce60488e6ec52283efb32efddaf93a","analyzedAt":"2026-08-20T13:07:44.778Z","contentChangedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}