{"id":"356a4903a58d857b","repo":"redis/node-redis","slug":"the-digest-function-requires-the-node-rs-xxhas","errorCode":null,"errorMessage":"The \"digest\" function requires the \"@node-rs/xxhash\" package, but it was not found.","messagePattern":"The \"digest\" function requires the \"@node-rs/xxhash\" package, but it was not found\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/utils/digest.ts","lineNumber":13,"sourceCode":"import { RedisArgument } from '../RESP/types';\n\ntype Xxh3Module = typeof import('@node-rs/xxhash').xxh3;\n\nlet xxh3Cache: Xxh3Module | null = null;\n\nasync function getXxh3(): Promise<Xxh3Module> {\n  if (!xxh3Cache) {\n    try {\n      const module = await import('@node-rs/xxhash');\n      xxh3Cache = module.xxh3;\n    } catch {\n      throw new Error(\n        'The \"digest\" function requires the \"@node-rs/xxhash\" package, but it was not found.'\n      );\n    }\n  }\n  return xxh3Cache;\n}\n\n/**\n * Computes a deterministic 64-bit XXH3 digest of the input.\n *\n * This produces the same digest that Redis computes internally via the `DIGEST` command,\n * allowing you to use it with conditional SET and DELEX operations (`IFDEQ`, `IFDNE`).\n *\n * @param value - The value to compute the digest for (string or Buffer)\n * @returns A 16-character lowercase hexadecimal digest\n * @throws If the `@node-rs/xxhash` package is not found\n */\nexport async function digest(value: RedisArgument): Promise<string> {","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/redis/node-redis/blob/bb5beb56578573910e2ee8f39681edc214c41398/packages/client/lib/utils/digest.ts#L1-L31","documentation":"Thrown by getXxh3() in digest.ts when the dynamic import('@node-rs/xxhash') fails (digest.ts:12). @redis/client declares @node-rs/xxhash as an *optional* peer dependency (packages/client/package.json:30,36), so it is not installed automatically. The digest() helper computes the same XXH3 64-bit digest Redis uses internally for IFDEQ/IFDNE (SET) and DELEX conditional operations, and needs the native module to do so.","triggerScenarios":"Calling the exported digest(value) helper (directly, or via a wrapper that feeds matchValue to SET ... IFDEQ/IFDNE or DELEX) in a project that did not install @node-rs/xxhash; or where the install omitted the platform-specific native binary.","commonSituations":"Using SET IFDEQ/IFDNE or DELEX matchValue for the first time without adding the optional dep; installing in an environment whose platform triple has no prebuilt binary; a monorepo that hoisted the package but did not install it for the consuming workspace.","solutions":["Install the package: `npm install @node-rs/xxhash` (it is an optional peer dep, not auto-installed).","If install succeeds but import still fails, reinstall to fetch the platform binary: `npm rebuild @node-rs/xxhash` or remove node_modules and reinstall.","Confirm the platform is supported (linux/macos/windows gnu/musl/arm64 prebuilds ship per release).","Avoid calling digest() — compute the value another way — if you cannot add native deps."],"exampleFix":"// before: digest() throws because the optional dep is absent\nconst d = await digest(myValue);\nawait client.set('k', 'v', { condition: 'IFDEQ', matchValue: d });\n// after\n// npm install @node-rs/xxhash\nconst d = await digest(myValue);\nawait client.set('k', 'v', { condition: 'IFDEQ', matchValue: d });","handlingStrategy":"validation","validationCode":"// Detect the optional dep before calling digest().\nasync function hasXxh3() {\n  try { await import('@node-rs/xxhash'); return true; } catch { return false; }\n}\nif (!(await hasXxh3())) {\n  throw new Error('Run `npm install @node-rs/xxhash` to use digest()/IFDEQ/IFDNE.');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const d = await digest(value);\n} catch (e) {\n  if (e instanceof Error && /@node-rs\\/xxhash/.test(e.message)) {\n    // instruct the operator to install the optional peer dependency\n    console.error('Missing optional dependency: npm install @node-rs/xxhash');\n  }\n  throw e;\n}","preventionTips":["Add @node-rs/xxhash to package.json dependencies whenever you use digest()/IFDEQ/IFDNE/DELEX.","Run `npm ls @node-rs/xxhash` in CI for workspaces that compute digests.","Confirm the platform binary installs (rebuild if import fails after install)."],"tags":["dependencies","native-module","optional-peer","client"],"analyzedSha":"bb5beb56578573910e2ee8f39681edc214c41398","analyzedAt":"2026-08-03T19:09:15.686Z","schemaVersion":2}