{"record":{"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/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L70-L106","documentation":"Thrown by the multi-shard splitter for keynum-type findKeys specs when the numkeys argument position falls inside the key region. The numkeys argument must precede the keys so the splitter can rewrite it per sub-command (each sub-command's numkeys reflects only its own group count). If numkeys is inside the key region, rewriting it would overwrite a key, making the split ambiguous.","triggerScenarios":"A keynum key spec where keyNumIdx >= keyRegionStart; corrupted or malformed key spec metadata where the numkeys position overlaps with keys. This is a metadata integrity violation, not a caller error.","commonSituations":"No standard multi_shard command uses keynum specs (MSETX is curated out of multi_shard). This would fire only if metadata changes tag a keynum-spec command as multi_shard with an invalid spec layout.","solutions":["This indicates a malformed key spec in the command metadata — report the issue","Verify the command's key spec layout: numkeys must be at a lower index than firstKey","Do not manually tag keynum-spec commands as multi_shard without verifying the spec layout"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isNumkeysInKeyRegion(err: unknown): boolean {\n  return err instanceof Error && err.message.includes('numkeys argument inside the key region');\n}","tryCatchPattern":"try {\n  await cluster.sendCommand(false, 'CUSTOM_CMD', ['3', 'key1', 'key2', 'key3']);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('numkeys argument inside')) {\n    // malformed key spec metadata — report\n  } else {\n    throw err;\n  }\n}","preventionTips":["Verify the keynum spec layout: numkeys position must precede the key region","Do not manually tag keynum-spec commands as multi_shard without verifying the spec layout","Report the issue — this indicates malformed metadata"],"tags":["cluster","multi-shard","key-spec","metadata"],"backgroundTag":null,"analyzedSha":"90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58","analyzedAt":"2026-08-11T15:37:21.243Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}