{"record":{"id":"42c63a41ee53eea9","repo":"tursodatabase/turso","slug":"native-binding-package-version-mismatch-expected","errorCode":null,"errorMessage":"Native binding package version mismatch, expected 0.8.0-pre.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.","messagePattern":"Native binding package version mismatch, expected 0\\.8\\.0-pre\\.3 but got (.+?)\\. You can reinstall dependencies to fix this issue\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/sync/packages/native/index.js","lineNumber":432,"sourceCode":"        return binding\n      } catch (e) {\n        loadErrors.push(e)\n      }\n    } else {\n      loadErrors.push(new Error(`Unsupported architecture on Linux: ${process.arch}`))\n    }\n  } else if (process.platform === 'openharmony') {\n    if (process.arch === 'arm64') {\n      try {\n        return require('./sync.openharmony-arm64.node')\n      } catch (e) {\n        loadErrors.push(e)\n      }\n      try {\n        const binding = require('@tursodatabase/sync-openharmony-arm64')\n        const bindingPackageVersion = require('@tursodatabase/sync-openharmony-arm64/package.json').version\n        if (bindingPackageVersion !== '0.8.0-pre.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {\n          throw new Error(`Native binding package version mismatch, expected 0.8.0-pre.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)\n        }\n        return binding\n      } catch (e) {\n        loadErrors.push(e)\n      }\n    } else if (process.arch === 'x64') {\n      try {\n        return require('./sync.openharmony-x64.node')\n      } catch (e) {\n        loadErrors.push(e)\n      }\n      try {\n        const binding = require('@tursodatabase/sync-openharmony-x64')\n        const bindingPackageVersion = require('@tursodatabase/sync-openharmony-x64/package.json').version\n        if (bindingPackageVersion !== '0.8.0-pre.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {\n          throw new Error(`Native binding package version mismatch, expected 0.8.0-pre.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)\n        }\n        return binding","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/javascript/sync/packages/native/index.js#L414-L450","documentation":"The napi-rs generated loader for @tursodatabase/sync-native verifies that the platform-specific native package (@tursodatabase/sync-openharmony-arm64 here) has exactly the same version as the JavaScript wrapper (0.8.0-pre.3). When NAPI_RS_ENFORCE_VERSION_CHECK is set to a value other than '0', a mismatch aborts loading of that binding. This protects against subtle ABI breakage when a stale optional dependency ships an older or newer .node binary than the JS API expects.","triggerScenarios":"Running on OpenHarmony with process.arch === 'arm64', where the local ./sync.openharmony-arm64.node require failed, so the loader falls back to the npm package @tursodatabase/sync-openharmony-arm64 whose package.json version differs from 0.8.0-pre.3, while the environment variable NAPI_RS_ENFORCE_VERSION_CHECK is set and not '0'.","commonSituations":"A half-updated install where package-lock.json pinned the optional dependency to an older release; CI environments that set NAPI_RS_ENFORCE_VERSION_CHECK=1 globally; mixed versions after 'npm update @tursodatabase/sync-native' without updating platform packages; caching proxies (Artifactory/Nexus) serving a stale platform package.","solutions":["Remove node_modules and package-lock.json, then run 'npm i' so the optional dependency resolves to the matching 0.8.0-pre.3 release","Explicitly install the matching platform package: npm i @tursodatabase/sync-openharmony-arm64@0.8.0-pre.3","As a temporary escape hatch, set NAPI_RS_ENFORCE_VERSION_CHECK=0 to skip the strict check (only if you know the ABI is compatible)","If you vendored the .node file, ensure ./sync.openharmony-arm64.node is present so the loader never falls back to the npm package"],"exampleFix":"# before\nnpm i @tursodatabase/sync-native@0.8.0-pre.3\n# installs @tursodatabase/sync-openharmony-arm64@0.8.0-pre.2 from a stale lockfile -> throws\n\n# after\nrm -rf node_modules package-lock.json\nnpm i @tursodatabase/sync-native@0.8.0-pre.3\n# or pin explicitly:\nnpm i @tursodatabase/sync-openharmony-arm64@0.8.0-pre.3","handlingStrategy":"validation","validationCode":"// before import, verify the platform package matches the wrapper version\nconst pkg = require('@tursodatabase/sync-native/package.json');\nconst plat = require('@tursodatabase/sync-openharmony-arm64/package.json');\nif (pkg.version !== plat.version) {\n  throw new Error(`Version skew: wrapper ${pkg.version} vs native ${plat.version} - run npm i`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const { Database } = await import('@tursodatabase/sync-native');\n} catch (e) {\n  for (const cause of e.cause ?? []) console.error('binding load failure:', cause?.message);\n  console.error('Fix: rm -rf node_modules package-lock.json && npm i');\n  process.exit(1);\n}","preventionTips":["Pin @tursodatabase/sync-native and every @tursodatabase/sync-* platform package to the same exact version (no ranges)","Run npm ls @tursodatabase/sync-openharmony-arm64 in CI to catch version skew before runtime","Avoid setting NAPI_RS_ENFORCE_VERSION_CHECK globally in CI images unless versions are also strictly pinned"],"tags":["napi-rs","native-binding","version-mismatch","openharmony","optional-dependencies"],"backgroundTag":"native-module-version-mismatch","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}