{"record":{"id":"e12d0dc92cd7697e","repo":"redis/node-redis","slug":"cannot-split-label-invalid-keystep-keystep","errorCode":null,"errorMessage":"Cannot split ${label}: invalid keystep ${keyStep}","messagePattern":"Cannot split (.+?): invalid keystep (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":102,"sourceCode":"      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);\n    if (groups) {\n      groups.push(group);\n    } else {\n      slotGroups.set(slot, [group]);","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/redis/node-redis/blob/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L84-L120","documentation":"Thrown by the multi-shard splitter when the keyStep value extracted from a command's key specification is less than 1. keyStep defines how many arguments each key group spans (e.g., MSET has keyStep 2: key + value). A step of 0 or negative is structurally invalid and would cause an infinite loop or divide-by-zero in the grouping logic.","triggerScenarios":"A multi_shard command's KeySpec declares keyStep < 1. This is a metadata bug — no shipped command has this value.","commonSituations":"Library regression after updating command metadata definitions; custom module command with an incorrect key specification.","solutions":["Report the bug to node-redis maintainers with the command name and version","Verify custom module command key specs declare keyStep >= 1","Work around by avoiding the cluster multi-shard routing path for the affected command"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// This guard fires on library metadata bugs, not user input.\ntry {\n  await client.mSet(pairs);\n} catch (e) {\n  if (e.message.includes('invalid keystep')) {\n    // Library metadata regression — report the issue\n  }\n}","preventionTips":["Pin to a stable node-redis release","Run integration tests against the cluster after library upgrades","Report metadata issues with the command name and library version"],"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"}