can1357/oh-my-pi · critical · Error

Failed to load pi_natives native addon for ${ctx.addonLabel}

Error message

Failed to load pi_natives native addon for ${ctx.addonLabel}.\n\nTried:\n${details}\n\n${buildHelpMessage(ctx)}

What it means

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.

Source

Thrown at packages/natives/native/loader-state.js:887

			installNativeTokioRuntime(bindings);
	        cleanupStaleNativeVersions({ nativesDir: ctx.nativesDir, currentVersion: ctx.packageVersion });
			startupMarker("native:loadNative:done");
			return bindings;
		} catch (err) {
			const message = err instanceof Error ? err.message : String(err);
			errors.push(`${candidate}: ${message}`);
		}
	}

	if (!SUPPORTED_PLATFORMS.includes(ctx.platformTag)) {
		throw new Error(
			`Unsupported platform: ${ctx.platformTag}\n` +
				`Supported platforms: ${SUPPORTED_PLATFORMS.join(", ")}\n` +
				"If you need support for this platform, please open an issue.",
		);
	}
	const details = errors.map(error => `- ${error}`).join("\n");
	throw new Error(
		`Failed to load pi_natives native addon for ${ctx.addonLabel}.\n\nTried:\n${details}\n\n${buildHelpMessage(ctx)}`,
	);
}

View on GitHub (pinned to 9690622007)

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).

Example fix

// before: stale ABI after runtime upgrade
$ node -e "require('@oh-my-pi/pi-natives')"  # ERR_DLOPEN_FAILED, MODULE_VERSION mismatch
// after
$ rm -rf node_modules && bun install   # fetches prebuilt matching current runtime

Defensive patterns

Strategy: try-catch

Validate before calling

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
function canLoadNativeAddon(candidatePath) {
  try { require(candidatePath); return true; } catch (err) {
    // log err.message (dlopen / MODULE_VERSION / glibc details) for diagnosis
    return false;
  }
}

Try / catch

try {
  loadNative(ctx);
} catch (err) {
  if (err.message.startsWith("Failed to load pi_natives native addon")) {
    // parse the `Tried:` bullets; trigger guided reinstall or fall back to JS implementations
  } else throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/8ba4c852dbe82880. Report an issue: GitHub.