h64 is not supported in Worker shim, use h64ToString instead

Error message

h64 is not supported in Worker shim, use h64ToString instead

What it means

The xxhash-wasm Workers shim (lib/shims/xxhash-wasm.ts) implements h64ToString with a synchronous JS fallback but cannot implement h64 (returning bigint) — the original used async SHA-256-backed hashing that cannot be made synchronous in Workers. h64 throws by design to redirect callers to h64ToString, which is the only variant actually used in the codebase (cache.ts, status.ts, several routes).

Source

Thrown at lib/shims/xxhash-wasm.ts:59

                    chunks.push(typeof input === 'string' ? encoder.encode(input) : input);
                    return this;
                },
                digest() {
                    const totalLength = chunks.reduce((sum, arr) => sum + arr.length, 0);
                    const combined = new Uint8Array(totalLength);
                    let offset = 0;
                    for (const chunk of chunks) {
                        combined.set(chunk, offset);
                        offset += chunk.length;
                    }
                    return simpleHash32(combined, seed);
                },
            };
        },
        // h64 methods use async SHA-256 but return sync - this is a limitation
        // In practice, only h64ToString is used and it's called with await xxhash()
        h64: (_input: string, _seed?: bigint): bigint => {
            throw new Error('h64 is not supported in Worker shim, use h64ToString instead');
        },
        h64ToString: (input: string, _seed?: bigint): string => {
            // This needs to be sync to match the API, but we use a simple hash
            // The actual usage in cache.ts awaits xxhash() first, so this works
            let hash = 0n;
            const data = encoder.encode(input);
            for (const byte of data) {
                hash = ((hash << 5n) - hash + BigInt(byte)) & 0xff_ff_ff_ff_ff_ff_ff_ffn;
            }
            return hash.toString(16).padStart(16, '0');
        },
        h64Raw: (_inputBuffer: Uint8Array, _seed?: bigint): bigint => {
            throw new Error('h64Raw is not supported in Worker shim');
        },
        create64: (_seed?: bigint): XXHash<bigint> => {
            throw new Error('create64 is not supported in Worker shim');
        },
    };

View on GitHub (pinned to bed535e087)

Solutions

Use h64ToString instead — it returns the same hash as a hex string and is the codebase standard.
If a bigint is truly required, run that code path on the Node runtime where the real wasm h64 is available.
Where h64ToString is used as a guid/key, ensure uniqueness the same way existing routes do (concat with link/id).

Example fix

// before
const { h64 } = await xxhash();
const key = h64(input); // throws under Workers
// after
const { h64ToString } = await xxhash();
const key = h64ToString(input); // works under Workers

Defensive patterns

Strategy: fallback

Validate before calling

// choose the Workers-safe variant up front
import xxhash from '@/shims/xxhash-wasm';
function pickHashMethod(needsBigInt: boolean) {
  const isWorkers = typeof process === 'undefined';
  if (needsBigInt && isWorkers) {
    throw new Error('h64 (bigint) is unavailable under Workers — use h64ToString');
  }
  return needsBigInt ? 'h64' : 'h64ToString';
}

Type guard

function isH64ShimError(e: unknown): e is Error {
  return e instanceof Error && /h64 is not supported in Worker shim/.test(e.message);
}

Try / catch

const api = await xxhash();
let key: string;
try {
  key = api.h64ToString(input); // preferred, Workers-safe
} catch (e) {
  if (isH64ShimError(e)) key = api.h64ToString(input); // never reached for h64ToString itself
  throw e;
}
// if you must call h64():
//   try { const n = api.h64(input); }
//   catch (e) { if (isH64ShimError(e)) key = api.h64ToString(input); else throw e; }

Prevention

Always use h64ToString — it is the codebase standard and works under Workers.
Do not copy h64 examples from xxhash-wasm docs into Worker-deployed routes.
Reserve bigint h64 for Node-runtime-only code paths.

When it happens

Trigger: Calling (await xxhash()).h64(input) — the bigint-returning variant — under Workers. h64ToString, h32 and h32ToString all work; only h64/h64Raw/create64 throw.

Common situations: A new route copied from xxhash-wasm docs that uses h64 directly; logic that needs a numeric bigint hash key; migrating Node code that called h64.

Related errors

AI-assisted analysis of DIYgod/RSSHub@bed535e087 (2026-08-12). Data as JSON: /api/errors/ebb31d67559ead80. Report an issue: GitHub.