{"record":{"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/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L80-L116","documentation":"Thrown by the cluster multi-shard splitter when a command's key specification declares a find_keys type other than 'range' or 'keynum'. The splitter needs to know the exact key layout to safely split a multi-key write across shards; an unknown find_keys type makes deterministic splitting impossible, so it refuses rather than risk corrupting data. No shipped multi_shard command currently reaches this branch.","triggerScenarios":"A command registered as multi_shard in command-metadata whose KeySpec.findKeys.type is neither 'range' nor 'keynum'. Only reachable via custom module commands with exotic key specs or a library metadata regression.","commonSituations":"Using a custom Redis module command marked multi_shard with an unrecognized find_keys spec; a library bug after upgrading where command metadata is corrupted.","solutions":["File a bug against node-redis — this guard fires on library metadata, not user input","If using a custom module command, verify its COMMAND DOCS output declares range or keynum find_keys","Avoid routing the affected command through the cluster multi-shard path by using sendCommand or a single-node route"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Wrap cluster commands in try-catch; if this fires it's a library metadata bug.\ntry {\n  await client.del('key1', 'key2');\n} catch (e) {\n  if (e.message.startsWith('Cannot split')) {\n    // Report to node-redis maintainers; avoid this command in cluster mode\n  }\n}","preventionTips":["Use shipped multi_shard commands (DEL, UNLINK, EXISTS, TOUCH, MGET, MSET) through their typed API only","Avoid registering custom module commands as multi_shard with unsupported find_keys types","Pin to a known-good node-redis version and test command metadata after upgrades"],"tags":["cluster","internal","command-metadata","multi-shard"],"backgroundTag":null,"analyzedSha":"90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58","analyzedAt":"2026-08-11T15:37:21.243Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}