Skip to content

Revision 1 — the current text. The evidence on this page is this revision’s own — it has not been carried forward from, or to, any other revision.

Diagnosing a Bun panic loading a native addon

Confirms the failure is specific to Bun (by checking the same code under plain Node) before treating it as a Bun compatibility regression, then checks for a documented compatible module/Bun version pairing to pin to. This is intentionally left diagnostic rather than prescriptive beyond that point: Bun's native-addon compatibility is an evolving, partial implementation, and asserting a specific cause for a specific version pair without checking that pair's actual changelog/issues would be a guess, not a fact.

Bun
Unverifiedno reproductions yetWhy this confidence?
Revision 1published by DevYou curation

Symptoms

The diagnostic path

6 steps, exactly as this revision published them.

  1. Step 1 · StartBun panics loading a native addon after a version upgrade

    Bun's support for native (.node) Node-API addons is not a complete implementation of Node's N-API/ABI surface, and what it does implement has changed across releases — so a module that happened to work on one Bun version can regress on a later one without any change to your own code or the addon.

    What happens next

    • passed → step 2, Does the exact same code work under plain Node.js instead of Bun?

  2. Step 2 · TestDoes the exact same code work under plain Node.js instead of Bun?

    This is the single most useful check: it separates a Bun-specific compatibility gap from a genuinely broken native module.

    Read-onlysh
    node -e "require('<native-module>')"

    Expected result

    (loads without error)

    What happens next

    • passed → step 3, Is there a documented compatible pairing of module version and Bun version?
    • failed → step 4, This isn't Bun-specific
    • unknown → step 4, This isn't Bun-specific

  3. Step 3 · TestIs there a documented compatible pairing of module version and Bun version?

    Check the native module's own README/issues for stated Bun compatibility, and check bun --version against any minimum/maximum Bun version the module documents.

    Read-onlysh
    bun --version

    Expected result

    1.2.4

    What happens next

    • passed → step 5, Fix: pin to the documented compatible pairing
    • failed → step 6, Root cause: unresolved Bun/native-addon incompatibility
    • unknown → step 6, Root cause: unresolved Bun/native-addon incompatibility

  4. Step 4 · EndThis isn't Bun-specific

    If it also fails under plain Node, the addon itself is broken for this platform — most likely the wrong prebuilt binary architecture, or it needs rebuilding: npm rebuild <module-name>, or re-running its install script. Chase it as a normal native-module build problem, not a Bun panic.

  5. Step 5 · FixFix: pin to the documented compatible pairing

    Pin either the native module or the Bun runtime itself to the last version documented as working together, until the incompatibility is resolved upstream. Re-run your test suite afterward — pinning an older module or runtime version can reintroduce other bugs that were fixed since.

    Changes statesh

    Changes system or service state. Review before running.

    Changes the installed version of the native module for this project (updating package.json and bun.lockb); it does not affect the Bun runtime itself unless you separately pin that via your version manager.

    bun add <module-name>@<compatible-version>

  6. Step 6 · Root causeRoot cause: unresolved Bun/native-addon incompatibility

    No documented compatible pairing exists yet. There is no generic fix to hand you here, because it depends on exactly which N-API surface the addon uses that this Bun version doesn't yet implement correctly. Practical options are running this part of the app under Node instead of Bun (a small Node-run subprocess or worker), or filing/tracking the issue upstream in Bun's own repository.

Why this confidence?

What would strengthen it: 6 more independent reproductions. Reproductions from 3 more distinct environments.

This counts only what was recorded against revision 1 itself. Nothing reported against another revision is included here — see the revision history for why.