{"id":"9286b6fe7ea39e48","repo":"redis/node-redis","slug":"cannot-split-label-unsupported-begin-search-ty","errorCode":null,"errorMessage":"Cannot split ${label}: unsupported begin_search type '${beginSearch.type}'","messagePattern":"Cannot split (.+?): unsupported begin_search type '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":61,"sourceCode":"  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.\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;","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/redis/node-redis/blob/bb5beb56578573910e2ee8f39681edc214c41398/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L43-L79","documentation":"splitMultiShardCommand only supports `begin_search.type === 'index'` (keys begin at a fixed position). A `keyword` begin_search (e.g. STORE-prefixed) or `unknown` (malformed/unparseable spec) cannot be split deterministically from the spec alone, so the splitter refuses. Current multi_shard commands all use index begin_search.","triggerScenarios":"A command tagged multi_shard whose key spec uses a `keyword` or `unknown` begin_search type. Reachable only via metadata change tagging such a command; not user-argument-triggered.","commonSituations":"A new command whose key region begins after a keyword rather than at a fixed index; a metadata regeneration where the spec decoded to `unknown` (e.g. RESP2/RESP3 spec normalization failure) but the command was still tagged multi_shard.","solutions":["Confirm the command's key region begins at a fixed index; if not, it is not a fit for multi_shard.","Re-run metadata generation — an `unknown` begin_search usually means the spec failed to decode (see transformBeginSearch).","Re-tag the command to default-keyed routing in overrides if the spec is keyword-based."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isIndexBeginSearch(spec: unknown): spec is { type: 'index'; index: number } {\n  return typeof spec === 'object' && spec !== null && (spec as { type?: string }).type === 'index';\n}","tryCatchPattern":"try {\n  await cluster.del('k1', 'k2');\n} catch (e) {\n  if (/unsupported begin_search type/.test(e.message)) {\n    // spec is keyword/unknown — re-tag command or regenerate metadata\n  } else throw e;\n}","preventionTips":["Only tag commands whose keys begin at a fixed index as multi_shard.","An `unknown` begin_search usually means the spec failed to decode — re-run metadata generation.","Route keyword-based key commands default-keyed."],"tags":["cluster","multi-shard","metadata","keyspec","splitter"],"analyzedSha":"bb5beb56578573910e2ee8f39681edc214c41398","analyzedAt":"2026-08-03T19:09:15.686Z","schemaVersion":2}