redis/node-redis · error · Error

The "digest" function requires the "@node-rs/xxhash" package

Error message

The "digest" function requires the "@node-rs/xxhash" package, but it was not found.

What it means

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.

Source

Thrown at packages/client/lib/utils/digest.ts:13

import { RedisArgument } from '../RESP/types';

type Xxh3Module = typeof import('@node-rs/xxhash').xxh3;

let xxh3Cache: Xxh3Module | null = null;

async function getXxh3(): Promise<Xxh3Module> {
  if (!xxh3Cache) {
    try {
      const module = await import('@node-rs/xxhash');
      xxh3Cache = module.xxh3;
    } catch {
      throw new Error(
        'The "digest" function requires the "@node-rs/xxhash" package, but it was not found.'
      );
    }
  }
  return xxh3Cache;
}

/**
 * Computes a deterministic 64-bit XXH3 digest of the input.
 *
 * This produces the same digest that Redis computes internally via the `DIGEST` command,
 * allowing you to use it with conditional SET and DELEX operations (`IFDEQ`, `IFDNE`).
 *
 * @param value - The value to compute the digest for (string or Buffer)
 * @returns A 16-character lowercase hexadecimal digest
 * @throws If the `@node-rs/xxhash` package is not found
 */
export async function digest(value: RedisArgument): Promise<string> {

View on GitHub (pinned to bb5beb5657)

Solutions

1. Install the package: `npm install @node-rs/xxhash` (it is an optional peer dep, not auto-installed).
2. If install succeeds but import still fails, reinstall to fetch the platform binary: `npm rebuild @node-rs/xxhash` or remove node_modules and reinstall.
3. Confirm the platform is supported (linux/macos/windows gnu/musl/arm64 prebuilds ship per release).
4. Avoid calling digest() — compute the value another way — if you cannot add native deps.

Example fix

// before: digest() throws because the optional dep is absent
const d = await digest(myValue);
await client.set('k', 'v', { condition: 'IFDEQ', matchValue: d });
// after
// npm install @node-rs/xxhash
const d = await digest(myValue);
await client.set('k', 'v', { condition: 'IFDEQ', matchValue: d });

// Detect the optional dep before calling digest().
async function hasXxh3() {
  try { await import('@node-rs/xxhash'); return true; } catch { return false; }
}
if (!(await hasXxh3())) {
  throw new Error('Run `npm install @node-rs/xxhash` to use digest()/IFDEQ/IFDNE.');
}

try {
  const d = await digest(value);
} catch (e) {
  if (e instanceof Error && /@node-rs\/xxhash/.test(e.message)) {
    // instruct the operator to install the optional peer dependency
    console.error('Missing optional dependency: npm install @node-rs/xxhash');
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

AI-assisted analysis of redis/node-redis@bb5beb5657 (2026-08-03). Data as JSON: /data/errors/356a4903a58d857b.json. Report an issue: GitHub.