tursodatabase/turso · error · Error

Native binding package version mismatch, expected…

Error message

Native binding package version mismatch, expected 0.8.0-pre.11 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.

What it means

This is a napi-rs generated loader in @tursodatabase/database-native. When running on Android arm64 it loads the platform package @tursodatabase/database-android-arm64 and compares its package.json version against the JS wrapper's own version ('0.8.0-pre.11'). If they differ and the check is enforced (NAPI_RS_ENFORCE_VERSION_CHECK set to anything other than '0'), it throws to prevent running a native binary that may not match the JS API surface.

Solutions

Reinstall dependencies from a clean state: rm -rf node_modules && npm install (or the equivalent for your package manager) so the platform package version matches 0.8.0-pre.11.
Check the installed version with `npm ls @tursodatabase/database-android-arm64` and explicitly install @tursodatabase/database-android-arm64@0.8.0-pre.11.
Clear the package manager cache (npm cache clean --force / pnpm store prune) if a stale 0.8.0-pre.X tarball keeps being resolved.
Set NAPI_RS_ENFORCE_VERSION_CHECK=0 to skip the check only if you knowingly run a mismatched native binary (not recommended).

Example fix

// before (package.json)
"dependencies": { "@tursodatabase/database-native": "^0.8.0-pre.11" }

// after: pin wrapper and platform package to the same version
npm install @tursodatabase/database-native@0.8.0-pre.11
npm install @tursodatabase/database-android-arm64@0.8.0-pre.11

Defensive patterns

Strategy: try-catch

Validate before calling

const wrapperPkg = require('@tursodatabase/database-native/package.json');
let platformPkg;
try { platformPkg = require('@tursodatabase/database-android-arm64/package.json'); } catch { platformPkg = null; }
if (platformPkg && platformPkg.version !== wrapperPkg.version) {
  throw new Error(`Install mismatch: @tursodatabase/database-android-arm64@${platformPkg.version} vs wrapper@${wrapperPkg.version}. Reinstall dependencies.`);
}

Type guard

const isMatchingBinding = (pkg) => !!pkg && typeof pkg.version === 'string' && pkg.version === require('@tursodatabase/database-native/package.json').version;

Try / catch

let binding;
try {
  binding = require('@tursodatabase/database-native');
} catch (e) {
  if (String(e.message).includes('Native binding package version mismatch')) {
    console.error('Native/JS version mismatch: run `rm -rf node_modules && npm install` to realign @tursodatabase platform packages.');
  }
  throw e;
}

Prevention

Install @tursodatabase/database-native and all platform packages with exact (non-range) versions in package.json.
Commit a single lockfile and reinstall node_modules whenever the package version changes.
In CI, start from a fresh node_modules instead of caching across release upgrades, or key the cache on the lockfile hash.
Run a startup smoke test that requires the package so mismatches fail the build, not production.

When it happens

Trigger: Requiring @tursodatabase/database-native on process.platform==='android' && process.arch==='arm64' while the installed @tursodatabase/database-android-arm64 optional dependency has a version other than 0.8.0-pre.11, with NAPI_RS_ENFORCE_VERSION_CHECK enabled.

Common situations: Partial 'npm update' or lockfile merge that upgraded the JS wrapper but left the old optional dependency cached; pnpm/yarn dedupe hoisting a stale platform package; a mixed install after switching npm registries or using an outdated mirror.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of tursodatabase/turso@8d4a589f8d (2026-09-20). Data as JSON: /api/errors/52e6243f75131ed4. Report an issue: GitHub.

Appendix: source

Thrown at bindings/javascript/packages/native/index.js:85

function requireNative() {
  if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
    try {
      nativeBinding = require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
    } catch (err) {
      loadErrors.push(err)
    }
  } else if (process.platform === 'android') {
    if (process.arch === 'arm64') {
      try {
        return require('./turso.android-arm64.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        const binding = require('@tursodatabase/database-android-arm64')
        const bindingPackageVersion = require('@tursodatabase/database-android-arm64/package.json').version
        if (bindingPackageVersion !== '0.8.0-pre.11' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
          throw new Error(`Native binding package version mismatch, expected 0.8.0-pre.11 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
        }
        return binding
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'arm') {
      try {
        return require('./turso.android-arm-eabi.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        const binding = require('@tursodatabase/database-android-arm-eabi')
        const bindingPackageVersion = require('@tursodatabase/database-android-arm-eabi/package.json').version
        if (bindingPackageVersion !== '0.8.0-pre.11' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
          throw new Error(`Native binding package version mismatch, expected 0.8.0-pre.11 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
        }
        return binding

View on GitHub (pinned to 8d4a589f8d)