{"id":"1a3c0902cd395aa9","repo":"redis/node-redis","slug":"cannot-split-label-multiple-key-specifications","errorCode":null,"errorMessage":"Cannot split ${label}: multiple key specifications are not supported","messagePattern":"Cannot split (.+?): multiple key specifications are not supported","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":56,"sourceCode":" */\nexport function splitMultiShardCommand(\n  args: ReadonlyArray<RedisArgument>,\n  keySpecs: ReadonlyArray<KeySpec> | undefined\n): Map<number, SubCommand> {\n  const label = args.length > 0 ? args[0].toString() : '<empty>';\n\n  if (!keySpecs || keySpecs.length === 0) {\n    throw new Error(`Cannot split ${label}: command has no key specification`);\n  }\n  // TODO(multi-spec): a command whose keys are interchangeable but\n  // syntactically scattered (e.g. a fixed-position key plus a keyword-tail\n  // list) could legitimately be multi_shard with several specs, and\n  // multi-region reconstruction would be deterministic. No such command\n  // exists, and specs alone cannot distinguish that shape from linked-operand\n  // specs (GEORADIUS-like) where splitting is meaningless — so refuse until a\n  // real command motivates multi-region support.\n  if (keySpecs.length > 1) {\n    throw new Error(`Cannot split ${label}: multiple key specifications are not supported`);\n  }\n\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.","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/redis/node-redis/blob/bb5beb56578573910e2ee8f39681edc214c41398/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L38-L74","documentation":"splitMultiShardCommand refuses commands with more than one key specification. Multiple specs could mean either interchangeable scattered keys (splittable) or linked-operand specs like GEORADIUS (not splittable), and the spec shape alone cannot distinguish them — so the splitter refuses until a real command motivates multi-spec support. No current multi_shard command declares >1 spec.","triggerScenarios":"A command tagged multi_shard whose COMMAND INFO reports two or more key specifications. Reachable only via metadata change tagging such a command, not by user arguments.","commonSituations":"A future/new command that Redis tags multi_shard with several specs; a metadata override that incorrectly tags a multi-spec command as multi_shard.","solutions":["Verify the command should be multi_shard at all — multi-spec commands are often better routed default-keyed.","If splitting is genuinely required, extend splitMultiShardCommand to handle multi-region reconstruction (the TODO at multi-shard-splitter.ts:48 marks this).","Re-tag the command to a supported request policy in command-metadata overrides."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isSingleSpec(specs: unknown): specs is [object] {\n  return Array.isArray(specs) && specs.length === 1;\n}","tryCatchPattern":"try {\n  await cluster.del('k1', 'k2');\n} catch (e) {\n  if (/multiple key specifications/.test(e.message)) {\n    // command tagged multi_shard with >1 spec — re-tag or extend the splitter\n  } else throw e;\n}","preventionTips":["Don't tag multi-spec commands as multi_shard unless the splitter supports them.","Audit command-metadata overrides for multi-spec commands.","Extend splitMultiShardCommand (see TODO at multi-shard-splitter.ts:48) only if a real command needs it."],"tags":["cluster","multi-shard","metadata","keyspec","splitter"],"analyzedSha":"bb5beb56578573910e2ee8f39681edc214c41398","analyzedAt":"2026-08-03T19:09:15.686Z","schemaVersion":2}