redis/node-redis · error · Error

default-keyed reducer: split reply missing position hints

Error message

default-keyed reducer: split reply missing position hints

What it means

Thrown by the default-keyed response reducer during multi-shard reply reassembly when a sub-reply at position p lacks its position hint (groupIndices). This is an internal invariant violation: the split path was entered because at least one hint was defined, but a specific entry's hint is undefined. It indicates a bug in how routeMultiShard or a downstream router constructed the plan, not a caller error.

Source

Thrown at packages/client/lib/cluster/request-response-policies/dispatch.ts:273

  _parser: CommandParser,
  positionHints?: Array<Array<number> | undefined>
): Promise<T> => {
  const responses = await Promise.all(promises);

  // Unsplit (single-target read, or a multi_shard command that landed on one
  // slot): pass the sole reply through unchanged.
  if (!positionHints?.some(hint => hint !== undefined)) {
    return responses[0];
  }

  // Split multi_shard (e.g. MGET across slots): each sub-reply is an array in
  // its own group order; scatter element i back to its original group ordinal
  // so the result matches the caller's key order regardless of slot/arrival.
  const result: Array<unknown> = [];
  responses.forEach((reply, p) => {
    const indices = positionHints[p];
    if (!indices) {
      throw new Error('default-keyed reducer: split reply missing position hints');
    }
    const elements = reply as Array<unknown>;
    indices.forEach((groupIndex, i) => {
      result[groupIndex] = elements[i];
    });
  });
  return result as T;
};

/**
 * Response policies whose reducers compute over raw numbers (scalars or
 * number arrays). Per-node replies for these plans are decoded *without* the
 * caller's type mapping — a `NUMBER: String` mapping would otherwise feed
 * strings into the numeric aggregators and throw — and the caller's mapping
 * is applied to the aggregated result instead (`remapAggregateReply`).
 */
export const NUMERIC_AGG_POLICIES: ReadonlySet<ResponsePolicyWithDefaults> = new Set([
  RESPONSE_POLICIES_WITH_DEFAULTS.AGG_SUM,

View on GitHub (pinned to 90fd0652bc)

Solutions

1. Report this as a bug to the node-redis issue tracker with the exact command and arguments
2. If using custom command metadata overrides, verify the request and response policies are consistent
3. Avoid mixing multi_shard routing with non-multi_shard plan entries

When it happens

Trigger: This error should not occur under normal usage of supported multi_shard commands (DEL, EXISTS, MGET, MSET, TOUCH, UNLINK). It fires only if a code path produces a plan where some entries carry groupIndices and others do not while the reducer's split-path guard was already passed — likely a custom router or a metadata override creating inconsistent plan entries.

Common situations: Internal library bug after a code change to the routing pipeline; custom command definition that bypasses the standard multi_shard router while still hitting the default-keyed reducer; a metadata override that changes a command's response policy without updating its request policy.

Related errors

• Cannot split ${label}: command has no key specification
• Cannot split ${label}: multiple key specifications are not s
• Cannot split ${label}: unsupported begin_search type '${begi
• Cannot split ${label}: unsupported find_keys range (lastkey
• Cannot split ${label}: numkeys argument inside the key regio

AI-assisted analysis of redis/node-redis@90fd0652bc (2026-08-11). Data as JSON: /api/errors/91b1d01fdbc49c1c. Report an issue: GitHub.