{"id":"0c7dd2f3b7a4d065","repo":"redis/node-redis","slug":"cannot-split-label-unsupported-find-keys-type","errorCode":null,"errorMessage":"Cannot split ${label}: unsupported find_keys type '${findKeys.type}'","messagePattern":"Cannot split (.+?): unsupported find_keys type '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":98,"sourceCode":"      keyRegionEnd = args.length;\n      break;\n    }\n    case 'keynum': {\n      keyStep = findKeys.keyStep;\n      keyNumIdx = start + findKeys.keyNumIdx;\n      keyRegionStart = start + findKeys.firstKey;\n      if (keyNumIdx >= keyRegionStart) {\n        throw new Error(`Cannot split ${label}: numkeys argument inside the key region`);\n      }\n      const numKeys = parsePositiveInteger(args[keyNumIdx]);\n      if (numKeys === undefined) {\n        throw new Error(`Cannot split ${label}: malformed numkeys argument '${args[keyNumIdx]}'`);\n      }\n      keyRegionEnd = keyRegionStart + numKeys * keyStep;\n      break;\n    }\n    default:\n      throw new Error(`Cannot split ${label}: unsupported find_keys type '${findKeys.type}'`);\n  }\n\n  if (keyStep < 1) {\n    throw new Error(`Cannot split ${label}: invalid keystep ${keyStep}`);\n  }\n  if (keyRegionStart < 1 || keyRegionEnd > args.length) {\n    throw new Error(`Cannot split ${label}: key region overruns the arguments`);\n  }\n  const regionLength = keyRegionEnd - keyRegionStart;\n  if (regionLength <= 0 || regionLength % keyStep !== 0) {\n    throw new Error(`Cannot split ${label}: key region does not align with keystep ${keyStep}`);\n  }\n\n  const groupCount = regionLength / keyStep;\n  const slotGroups = new Map<number, Array<number>>();\n  for (let group = 0; group < groupCount; group++) {\n    const slot = calculateSlot(args[keyRegionStart + group * keyStep]);\n    const groups = slotGroups.get(slot);","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/redis/node-redis/blob/bb5beb56578573910e2ee8f39681edc214c41398/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L80-L116","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run metadata generation — an `unknown` find_keys usually means the spec failed to decode (check transformFindKeys).","Confirm the Redis version reports a supported spec type for the command.","Re-tag the command to default-keyed routing if its spec type is unsupported."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isSupportedFindKeys(spec: unknown): boolean {\n  if (typeof spec !== 'object' || spec === null) return false;\n  const t = (spec as { type?: string }).type;\n  return t === 'range' || t === 'keynum';\n}","tryCatchPattern":"try {\n  await cluster.del('k1', 'k2');\n} catch (e) {\n  if (/unsupported find_keys type/.test(e.message)) {\n    // spec decoded to unknown or a new type — regenerate metadata or re-tag\n  } else throw e;\n}","preventionTips":["An `unknown` find_keys usually means the spec failed to decode — re-run metadata generation.","Confirm the Redis version reports a supported spec type for the command.","Re-tag unsupported-spec commands to default-keyed routing."],"tags":["cluster","multi-shard","metadata","keyspec","splitter"],"analyzedSha":"bb5beb56578573910e2ee8f39681edc214c41398","analyzedAt":"2026-08-03T19:09:15.686Z","schemaVersion":2}