{"record":{"id":"8ba4c852dbe82880","repo":"can1357/oh-my-pi","slug":"failed-to-load-pi-natives-native-addon-for-ctx-a","errorCode":null,"errorMessage":"Failed to load pi_natives native addon for ${ctx.addonLabel}.\\n\\nTried:\\n${details}\\n\\n${buildHelpMessage(ctx)}","messagePattern":"Failed to load pi_natives native addon for (.+?)\\.\\\\n\\\\nTried:\\\\n(.+?)\\\\n\\\\n(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/natives/native/loader-state.js","lineNumber":887,"sourceCode":"\t\t\tinstallNativeTokioRuntime(bindings);\n\t        cleanupStaleNativeVersions({ nativesDir: ctx.nativesDir, currentVersion: ctx.packageVersion });\n\t\t\tstartupMarker(\"native:loadNative:done\");\n\t\t\treturn bindings;\n\t\t} catch (err) {\n\t\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\t\terrors.push(`${candidate}: ${message}`);\n\t\t}\n\t}\n\n\tif (!SUPPORTED_PLATFORMS.includes(ctx.platformTag)) {\n\t\tthrow new Error(\n\t\t\t`Unsupported platform: ${ctx.platformTag}\\n` +\n\t\t\t\t`Supported platforms: ${SUPPORTED_PLATFORMS.join(\", \")}\\n` +\n\t\t\t\t\"If you need support for this platform, please open an issue.\",\n\t\t);\n\t}\n\tconst details = errors.map(error => `- ${error}`).join(\"\\n\");\n\tthrow new Error(\n\t\t`Failed to load pi_natives native addon for ${ctx.addonLabel}.\\n\\nTried:\\n${details}\\n\\n${buildHelpMessage(ctx)}`,\n\t);\n}\n","sourceCodeStart":869,"sourceCodeEnd":891,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/natives/native/loader-state.js#L869-L891","documentation":"This is the terminal error of the native loading path: after every candidate strategy fails — embedded addon extraction, staged node_modules copy, and direct .node requires — the loader throws an aggregate error naming ctx.addonLabel, one bullet per failed candidate with its underlying message, plus a contextual help message from buildHelpMessage(ctx). It tells you the library could not obtain a working pi_natives binary on this machine at all.","triggerScenarios":"loadNative() exhausts all candidate .node paths: extraction from the embedded archive failed (errors 3000-3005), staging/copying failed, and requiring each candidate .node threw (missing file, wrong NODE_MODULE_VERSION, glibc/musl mismatch, permission denied, corrupt binary). All messages are collected into `details` and rethrown wrapped.","commonSituations":"Corrupt or incomplete install (missing .node files); ABI mismatch after a Node/Bun major upgrade (NODE_MODULE_VERSION changed); missing system libraries (glibc too old for the prebuilt, musl vs glibc on Alpine); antivirus quarantining the .node; read-only or permission-restricted install directories.","solutions":["Read the `Tried:` bullets for the root cause, then fix that underlying error first.","Reinstall the package cleanly: rm -rf node_modules/<pkg> and reinstall, so the correct prebuilt .node for your platform/ABI is fetched.","Match your runtime to the prebuilt ABI — upgrade/downgrade Node or Bun so NODE_MODULE_VERSION matches, or use the bundled binary distribution.","On Alpine/musl or unusual distros, install a glibc-based environment or build pi-natives from source.","Check permissions/antivirus: ensure the native directory is writable and the .node file is not quarantined (chmod 755, whitelist the path)."],"exampleFix":"// before: stale ABI after runtime upgrade\n$ node -e \"require('@oh-my-pi/pi-natives')\"  # ERR_DLOPEN_FAILED, MODULE_VERSION mismatch\n// after\n$ rm -rf node_modules && bun install   # fetches prebuilt matching current runtime","handlingStrategy":"try-catch","validationCode":"import { createRequire } from \"node:module\";\nconst require = createRequire(import.meta.url);\nfunction canLoadNativeAddon(candidatePath) {\n  try { require(candidatePath); return true; } catch (err) {\n    // log err.message (dlopen / MODULE_VERSION / glibc details) for diagnosis\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  loadNative(ctx);\n} catch (err) {\n  if (err.message.startsWith(\"Failed to load pi_natives native addon\")) {\n    // parse the `Tried:` bullets; trigger guided reinstall or fall back to JS implementations\n  } else throw err;\n}","preventionTips":["Reinstall cleanly (remove node_modules / package cache) rather than patching in place after runtime upgrades.","Keep Node/Bun versions within the range the package's prebuilds target (NODE_MODULE_VERSION).","Verify the install with a require() smoke test in postinstall/CI before shipping.","Check glibc version on Linux deploys (ldd --version) against the prebuilt's minimum; use musl builds on Alpine.","Ensure install directories are writable and antivirus doesn't quarantine .node files."],"tags":["native-addon","load-failure","installation","abi-mismatch"],"backgroundTag":"native-addon-load-failed","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}