{"record":{"id":"803ca0194d93c228","repo":"redis/node-redis","slug":"cannot-split-label-unsupported-find-keys-range","errorCode":null,"errorMessage":"Cannot split ${label}: unsupported find_keys range (lastkey ${findKeys.lastKey}, limit ${findKeys.limit})","messagePattern":"Cannot split (.+?): unsupported find_keys range \\(lastkey (.+?), limit (.+?)\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":76,"sourceCode":"\n  const { beginSearch, findKeys } = keySpecs[0];\n  if (beginSearch.type !== 'index') {\n    throw new Error(`Cannot split ${label}: unsupported begin_search type '${beginSearch.type}'`);\n  }\n\n  const start = beginSearch.index;\n  let keyRegionStart: number;\n  let keyRegionEnd: number;\n  let keyStep: number;\n  // Absolute position of the numkeys argument to rewrite per sub-command.\n  let keyNumIdx: number | undefined;\n\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;","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/redis/node-redis/blob/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L58-L94","documentation":"Thrown by the multi-shard splitter when a range-type findKeys spec has a bounded range (lastKey >= 0 or limit != 0). The splitter currently only supports 'until end of args' ranges (lastKey=-1, limit=0) because all standard multi_shard commands use open-ended ranges. Bounded ranges would require additional logic to handle keys that don't extend to the end of the argument list.","triggerScenarios":"A multi_shard command whose range key spec has lastKey >= 0 (bounded) or a non-zero limit (key step filtering); a metadata change or dynamic resolution that introduces such a spec.","commonSituations":"Metadata regeneration tags a command with a bounded range as multi_shard; a future Redis command with a bounded key range is tagged multi_shard. All current multi_shard commands (DEL, EXISTS, MGET, MSET, TOUCH, UNLINK) use lastKey=-1, limit=0.","solutions":["Verify the command's findKeys spec in COMMAND DOCS","Report the issue if a standard command triggers this — the splitter may need to be extended","If the command must be split, extend the range branch to handle bounded ranges and limits"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isUnsupportedFindKeysRange(err: unknown): boolean {\n  return err instanceof Error && err.message.includes('unsupported find_keys range');\n}","tryCatchPattern":"try {\n  await cluster.sendCommand(false, 'CUSTOM_CMD', ['key1', 'key2']);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('find_keys range')) {\n    // bounded range — route manually\n  } else {\n    throw err;\n  }\n}","preventionTips":["Verify the command's findKeys range spec — standard multi_shard commands use lastKey=-1, limit=0","Do not tag commands with bounded key ranges as multi_shard without extending the splitter","Report the issue if a standard multi_shard command triggers this"],"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"}