better-sqlite3 native module incompatibility on Node runtime upgrade (e.g. Node 26)

[Rahulsharma0810]

Describe the bug

When omniroute is installed globally via npm install -g omniroute on macOS, and the active Node.js version is subsequently updated or differs from the installation version (e.g., updating to Node v26.3.0 which uses NODE_MODULE_VERSION 147), the better-sqlite3 native module fails to load because it was compiled against a different version (e.g., NODE_MODULE_VERSION 127).

While OmniRoute gracefully detects this incompatibility and outputs a troubleshooting message:

✖ better-sqlite3 native module is incompatible with this platform.
  Run: cd /opt/homebrew/lib/node_modules/omniroute/dist && npm rebuild better-sqlite3

This failure causes background launchd services (such as com.rvs.omniroute.plist system/user daemons) to fail to start and crash repeatedly (exiting with code 1), making it hard to diagnose without manually reading logs or running the command directly in the shell.

To Reproduce

1. Install omniroute globally using Node 22: npm install -g omniroute
2. Update/switch Node version to v26.3.0.
3. Start the service (or run omniroute).
4. See dlopen failure warning and process exit code 1.

Possible Solutions / Suggestions

1. Self-Healing / Auto-Rebuild: If the CLI detects !isNativeBinaryCompatible(sqliteBinary) and the environment has write permissions to the directory, trigger/prompt npm rebuild better-sqlite3 automatically, or add a recovery command like omniroute repair.
2. Launchd Troubleshooting / Documentation: Add notes in the documentation about running npm rebuild better-sqlite3 when Node is updated.

[diegosouzapw]

Thanks @Rahulsharma0810. When the active Node.js major version changes after install, better-sqlite3's prebuilt native binary no longer matches the ABI (NODE_MODULE_VERSION), which is exactly what crashes the launchd/systemd service on start (exit 1).

Immediate fix (the one the CLI already prints): rebuild the native module against the current Node:

cd $(npm root -g)/omniroute/dist && npm rebuild better-sqlite3

OmniRoute already ships graceful detection + that troubleshooting message (#3025). The self-healing auto-rebuild / omniroute repair you suggest is a good enhancement — tracking it as a feature request. For the launchd crash-loop specifically, until auto-repair lands, either pin the Node version the service runs under, or add the npm rebuild step to your Node-upgrade routine.

[diegosouzapw]

Thanks for the well-structured report! A few notes:

Current behavior (by design): OmniRoute already detects the native module mismatch at startup and prints the exact rebuild command:

✖ better-sqlite3 native module is incompatible with this platform.
  Run: cd /path/to/omniroute/dist && npm rebuild better-sqlite3

This is intentional — auto-rebuild on startup could silently fail in environments without a C++ toolchain (Docker minimal images, CI, etc.) and would make startup non-deterministic.

For launchd/systemd services: The challenge is that the service crashes before the error message is visible. The current recommendation is:

1. Run omniroute manually once after a Node upgrade to see the rebuild message
2. Run the rebuild command
3. Restart the service

omniroute repair command: This is a good enhancement suggestion — a repair subcommand that runs npm rebuild better-sqlite3 in the right directory with proper error handling would be more discoverable than the startup warning. Tracking this as a feature request.

Immediate workaround (Node version pinning): If you use nvm or volta, pin the Node version for the OmniRoute service to match the one it was compiled against. This prevents the mismatch entirely on upgrades.

Note: OmniRoute supports Node ≥22 (and ≥24 in recent releases), so upgrading to Node 26 is fine — just rebuild after the upgrade.

[diegosouzapw]

The self-heal command you asked for already exists — omniroute runtime repair — which rebuilds better-sqlite3 into a user-writable runtime (~/.omniroute/runtime/), so it works even for a global install without a C++ toolchain. The real gap was discoverability: the ABI-mismatch error only mentioned npm rebuild.

Fixed in release/v3.8.25 (#3828): the startup + SQLite error messages now point to omniroute runtime repair, and a shorter top-level omniroute repair alias was added. So after a Node major upgrade: just run omniroute repair. It ships in the next release.