redis/node-redis · error · Error

Cannot split ${label}: unsupported find_keys type '${findKey

Error message

Cannot split ${label}: unsupported find_keys type '${findKeys.type}'

What it means

splitMultiShardCommand only handles `range` and `keynum` find_keys types. Any other type — including `unknown` (a spec that failed to decode in transformFindKeys) — is refused because the splitter cannot locate keys from it. This is a metadata/spec invariant, not user-triggered.

Source

Thrown at packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts:98

      keyRegionEnd = args.length;
      break;
    }
    case 'keynum': {
      keyStep = findKeys.keyStep;
      keyNumIdx = start + findKeys.keyNumIdx;
      keyRegionStart = start + findKeys.firstKey;
      if (keyNumIdx >= keyRegionStart) {
        throw new Error(`Cannot split ${label}: numkeys argument inside the key region`);
      }
      const numKeys = parsePositiveInteger(args[keyNumIdx]);
      if (numKeys === undefined) {
        throw new Error(`Cannot split ${label}: malformed numkeys argument '${args[keyNumIdx]}'`);
      }
      keyRegionEnd = keyRegionStart + numKeys * keyStep;
      break;
    }
    default:
      throw new Error(`Cannot split ${label}: unsupported find_keys type '${findKeys.type}'`);
  }

  if (keyStep < 1) {
    throw new Error(`Cannot split ${label}: invalid keystep ${keyStep}`);
  }
  if (keyRegionStart < 1 || keyRegionEnd > args.length) {
    throw new Error(`Cannot split ${label}: key region overruns the arguments`);
  }
  const regionLength = keyRegionEnd - keyRegionStart;
  if (regionLength <= 0 || regionLength % keyStep !== 0) {
    throw new Error(`Cannot split ${label}: key region does not align with keystep ${keyStep}`);
  }

  const groupCount = regionLength / keyStep;
  const slotGroups = new Map<number, Array<number>>();
  for (let group = 0; group < groupCount; group++) {
    const slot = calculateSlot(args[keyRegionStart + group * keyStep]);
    const groups = slotGroups.get(slot);

View on GitHub (pinned to bb5beb5657)

Solutions

1. Re-run metadata generation — an `unknown` find_keys usually means the spec failed to decode (check transformFindKeys).
2. Confirm the Redis version reports a supported spec type for the command.
3. Re-tag the command to default-keyed routing if its spec type is unsupported.

function isSupportedFindKeys(spec: unknown): boolean {
  if (typeof spec !== 'object' || spec === null) return false;
  const t = (spec as { type?: string }).type;
  return t === 'range' || t === 'keynum';
}

try {
  await cluster.del('k1', 'k2');
} catch (e) {
  if (/unsupported find_keys type/.test(e.message)) {
    // spec decoded to unknown or a new type — regenerate metadata or re-tag
  } else throw e;
}

When it happens

Trigger: A command tagged multi_shard whose findKeys.type is neither 'range' nor 'keynum' (e.g. 'unknown' from a decode failure, or a future spec type). Reachable only via metadata change.

Common situations: A metadata regeneration where the spec decoded to `unknown` (normalize failed) but the command was still tagged multi_shard; a future Redis spec type not yet handled by transformFindKeys.

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@bb5beb5657 (2026-08-03). Data as JSON: /data/errors/0c7dd2f3b7a4d065.json. Report an issue: GitHub.