{"record":{"id":"d82ceb5329dbf5fe","repo":"huggingface/tokenizers","slug":"native-binding-package-version-mismatch-expected","errorCode":null,"errorMessage":"Native binding package version mismatch, expected 0.15.3-dev0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.","messagePattern":"Native binding package version mismatch, expected 0\\.15\\.3-dev0 but got (.+?)\\. You can reinstall dependencies to fix this issue\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/node/index.js","lineNumber":85,"sourceCode":"    } catch (err) {\n      loadErrors.push(err)\n    }\n  } else if (process.platform === 'android') {\n    if (process.arch === 'arm64') {\n      try {\n        return require('./tokenizers.android-arm64.node')\n      } catch (e) {\n        loadErrors.push(e)\n      }\n      try {\n        const binding = require('tokenizers-android-arm64')\n        const bindingPackageVersion = require('tokenizers-android-arm64/package.json').version\n        if (\n          bindingPackageVersion !== '0.15.3-dev0' &&\n          process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&\n          process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'\n        ) {\n          throw new Error(\n            `Native binding package version mismatch, expected 0.15.3-dev0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,\n          )\n        }\n        return binding\n      } catch (e) {\n        loadErrors.push(e)\n      }\n    } else if (process.arch === 'arm') {\n      try {\n        return require('./tokenizers.android-arm-eabi.node')\n      } catch (e) {\n        loadErrors.push(e)\n      }\n      try {\n        const binding = require('tokenizers-android-arm-eabi')\n        const bindingPackageVersion = require('tokenizers-android-arm-eabi/package.json').version\n        if (\n          bindingPackageVersion !== '0.15.3-dev0' &&","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/huggingface/tokenizers/blob/6cfd9d385ca0ed91c10b49f0ce97d02cfde1b607/bindings/node/index.js#L67-L103","documentation":"This error is thrown by requireNative in bindings/node/index.js when the optional platform-specific native binding package (here tokenizers-android-arm64) has a version that does not match the version the main tokenizers package was compiled against (0.15.3-dev0). The main package pins its native binding packages so the JS wrapper and the prebuilt .node binary always agree; a mismatch means the loaded binary may be incompatible. The check is enforced only when the environment variable NAPI_RS_ENFORCE_VERSION_CHECK is set to a non-empty value other than '0'.","triggerScenarios":"Requiring the tokenizers module on an android-arm64 platform while the installed tokenizers-android-arm64 package's version !== '0.15.3-dev0', with NAPI_RS_ENFORCE_VERSION_CHECK set (e.g. to '1'). The thrown error is caught inside requireNative and pushed to loadErrors, typically surfacing later when no binding could be loaded.","commonSituations":"Partial installs after upgrading/downgrading tokenizers without reinstalling optional dependencies; lockfile or registry caching an old binding package; manually installed or hoisted mismatched binding versions; pnpm/yarn resolution pinning a stale optional dependency.","solutions":["Run the package manager's reinstall (e.g. `npm install`, `yarn install`, or `pnpm install`) so the matching tokenizers-android-arm64@0.15.3-dev0 optional dependency is installed.","Explicitly install the correct binding version: `npm i tokenizers-android-arm64@0.15.3-dev0`.","Clear lockfile/caches if a stale version keeps resolving (`npm cache clean --force`, delete lockfile, reinstall).","Unset NAPI_RS_ENFORCE_VERSION_CHECK (or set it to '0') to bypass the check only if you accept the version mismatch."],"exampleFix":"// before\nnpm ls tokenizers-android-arm64  # shows 0.15.2\n// after\nrm -rf node_modules package-lock.json && npm install\n# tokenizers-android-arm64 now resolves to 0.15.3-dev0","handlingStrategy":"try-catch","validationCode":"const ver = (() => { try { return require('tokenizers-android-arm64/package.json').version } catch { return null } })();\nif (ver && ver !== '0.15.3-dev0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {\n  throw new Error(`tokenizers-android-arm64 version ${ver} != 0.15.3-dev0; reinstall deps before importing tokenizers`);\n}","typeGuard":"function isBindingVersionOk(pkgName, expected = '0.15.3-dev0') {\n  try {\n    const v = require(`${pkgName}/package.json`).version;\n    return typeof v === 'string' && v === expected;\n  } catch {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  const { Tokenizer } = require('tokenizers');\n} catch (e) {\n  if (String(e.message).includes('version mismatch')) {\n    console.error('Native binding version mismatch: run `npm install` to reinstall platform bindings');\n  } else {\n    throw e;\n  }\n}","preventionTips":["After bumping tokenizers, always delete node_modules and the lockfile (or run npm ci) so optional platform bindings are refreshed.","Do not pin/override tokenizers-* platform packages to different versions in package.json.","Check installed binding versions in CI before running tests that import tokenizers.","Avoid `npm install --omit=optional` for apps that need the native binding.","Know that NAPI_RS_ENFORCE_VERSION_CHECK controls strictness; leave it set in CI to catch drift early."],"tags":["version-mismatch","native-binding","installation","nodejs"],"backgroundTag":"invalid-argument-value","analyzedSha":"6cfd9d385ca0ed91c10b49f0ce97d02cfde1b607","analyzedAt":"2026-09-09T11:43:25.027Z","contentChangedAt":"2026-09-09T11:43:25.027Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}