{"id":"0abf58763a1d4a83","repo":"redis/node-redis","slug":"cannot-split-label-numkeys-argument-inside-the","errorCode":null,"errorMessage":"Cannot split ${label}: numkeys argument inside the key region","messagePattern":"Cannot split (.+?): numkeys argument inside the key region","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":88,"sourceCode":"\n  switch (findKeys.type) {\n    case 'range': {\n      // All current multi_shard range specs are \"until end of args\"; bounded\n      // ranges (lastKey >= 0) and limit can be added when a command needs them.\n      if (findKeys.lastKey !== -1 || findKeys.limit !== 0) {\n        throw new Error(`Cannot split ${label}: unsupported find_keys range (lastkey ${findKeys.lastKey}, limit ${findKeys.limit})`);\n      }\n      keyStep = findKeys.keyStep;\n      keyRegionStart = start;\n      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  }","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/redis/node-redis/blob/bb5beb56578573910e2ee8f39681edc214c41398/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L70-L106","documentation":"For `keynum` specs, the numkeys argument's position (beginSearch.index + findKeys.keyNumIdx) must come BEFORE the key region (beginSearch.index + findKeys.firstKey). If the spec places numkeys inside the key region, per-slot rewriting of numkeys would corrupt the key sequence, so the splitter refuses. This is a spec-invariant violation, not a user-argument error.","triggerScenarios":"A command tagged multi_shard with a keynum spec where keyNumIdx resolves to a position at or after the key region start. No current shipped multi_shard command uses a keynum spec through this path (MSEDEX is curated OUT), so this is metadata/spec invariant only.","commonSituations":"A malformed or future keynum spec in metadata; a metadata regeneration capturing an unusual keynum layout.","solutions":["Verify the command's keynum spec layout in metadata — keyNumIdx must precede firstKey.","Re-run metadata generation if the spec looks wrong.","Re-tag the command away from multi_shard if its layout cannot be split."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await cluster.sendCommand(cmd, ...args);\n} catch (e) {\n  if (/numkeys argument inside the key region/.test(e.message)) {\n    // malformed keynum spec in metadata — regenerate or override\n  } else throw e;\n}","preventionTips":["Verify keynum specs in metadata place keyNumIdx before firstKey.","Re-run metadata generation if a keynum spec looks malformed.","Re-tag keynum commands away from multi_shard if their layout can't be split."],"tags":["cluster","multi-shard","metadata","keyspec","splitter"],"analyzedSha":"bb5beb56578573910e2ee8f39681edc214c41398","analyzedAt":"2026-08-03T19:09:15.686Z","schemaVersion":2}