{"record":{"id":"aca802a24db2368a","repo":"huggingface/tokenizers","slug":"failed-to-load-native-binding","errorCode":null,"errorMessage":"Failed to load native binding","messagePattern":"Failed to load native binding","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/node/index.js","lineNumber":734,"sourceCode":"    throw error\n  }\n}\n\nif (!nativeBinding) {\n  if (loadErrors.length > 0) {\n    throw new Error(\n      `Cannot find native binding. ` +\n        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +\n        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',\n      {\n        cause: loadErrors.reduce((err, cur) => {\n          cur.cause = err\n          return cur\n        }),\n      },\n    )\n  }\n  throw new Error(`Failed to load native binding`)\n}\n\nmodule.exports = nativeBinding\nmodule.exports.AddedToken = nativeBinding.AddedToken\nmodule.exports.BPE = nativeBinding.BPE\nmodule.exports.Bpe = nativeBinding.Bpe\nmodule.exports.Decoder = nativeBinding.Decoder\nmodule.exports.Encoding = nativeBinding.Encoding\nmodule.exports.JsEncoding = nativeBinding.JsEncoding\nmodule.exports.Model = nativeBinding.Model\nmodule.exports.Normalizer = nativeBinding.Normalizer\nmodule.exports.PreTokenizer = nativeBinding.PreTokenizer\nmodule.exports.Processor = nativeBinding.Processor\nmodule.exports.Tokenizer = nativeBinding.Tokenizer\nmodule.exports.Trainer = nativeBinding.Trainer\nmodule.exports.Unigram = nativeBinding.Unigram\nmodule.exports.WordLevel = nativeBinding.WordLevel\nmodule.exports.WordPiece = nativeBinding.WordPiece","sourceCodeStart":716,"sourceCodeEnd":752,"githubUrl":"https://github.com/huggingface/tokenizers/blob/6cfd9d385ca0ed91c10b49f0ce97d02cfde1b607/bindings/node/index.js#L716-L752","documentation":"Thrown when requireNative() found no binding (nativeBinding is falsy) but loadErrors is empty — i.e., the loader cannot even record why loading failed. Unlike the 'Cannot find native binding' error, it carries no npm-optional-dependency hint and no cause, making it the generic 'something silently prevented binding selection' failure at module load.","triggerScenarios":"Module-level code in bindings/node/index.js:734 executes with nativeBinding falsy and loadErrors.length === 0 — e.g. an environment where no platform branch set loadErrors yet every require returned falsy, or a monkey-patched/intercepted require returning undefined instead of throwing.","commonSituations":"Custom bundler/mocking setups (e.g. jest moduleNameMapper) that replace require with a function returning undefined; exotic embedded environments where no platform branch matched; unusual loader interception tools that swallow require errors.","solutions":["Re-run in plain Node (no require interception/mocks) to see if the error persists and inspect earlier console output","Delete node_modules and package-lock.json and reinstall, as with the 'Cannot find native binding' case","Verify you're on a supported platform/arch (check process.platform and process.arch); unsupported combos push descriptive errors into loadErrors — if you see this instead, something interfered with loading","Check bundler/test configs (webpack resolve, jest moduleNameMapper) for overrides of the binding modules"],"exampleFix":"// before (jest mock returning undefined)\njest.mock('tokenizers-linux-x64-gnu', () => undefined)\n// after\njest.mock('tokenizers-linux-x64-gnu', () => require('./__mocks__/binding.js'))","handlingStrategy":"try-catch","validationCode":"let tokenizers;\ntry { tokenizers = require('tokenizers'); } catch {}\nif (!tokenizers) {\n  console.error('Failed to load native binding; check platform support and bundler overrides');\n}","typeGuard":"function hasNativeBinding(mod) {\n  return !!mod && typeof mod === 'object' && Object.keys(mod).length > 0;\n}","tryCatchPattern":"try {\n  const tokenizers = require('tokenizers');\n} catch (err) {\n  if (err.message === 'Failed to load native binding') {\n    console.error('No load errors recorded — check for require mocks/overrides or unsupported platform:', process.platform, process.arch);\n  }\n  throw err;\n}","preventionTips":["Don't stub platform binding modules with jest.mock/webpack aliases that return undefined","Verify the target platform/arch is supported before deploying","Reproduce outside bundlers/interceptors to isolate the cause","Keep the loader file (bindings/node/index.js) unmodified in build pipelines"],"tags":["nodejs","native-binding","module-init","napi-rs"],"backgroundTag":"module-init-failed","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"}