{"record":{"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/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L43-L79","documentation":"Thrown by the multi-shard splitter when the key spec's beginSearch type is not 'index'. Redis COMMAND DOCS defines two begin_search types: 'index' (keys start at a fixed position) and 'keyword' (keys follow a keyword token). The splitter only supports 'index' because keyword-based key discovery makes deterministic splitting harder.","triggerScenarios":"A multi_shard command whose key spec uses keyword-based begin_search; a custom or unusual command tagged multi_shard whose keys are located via a keyword rather than a fixed index.","commonSituations":"Metadata regeneration or dynamic resolution tags a keyword-begin_search command as multi_shard; all standard multi_shard commands (DEL, EXISTS, MGET, MSET, TOUCH, UNLINK) use index-based begin_search, so this should not fire for them.","solutions":["Verify the command's key spec in COMMAND DOCS — if it uses keyword begin_search, it should not be tagged multi_shard","Report the issue if a standard multi_shard command triggers this","If the command must be split, consider extending the splitter to support keyword-based begin_search"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isUnsupportedBeginSearch(err: unknown): boolean {\n  return err instanceof Error && err.message.includes('unsupported begin_search type');\n}","tryCatchPattern":"try {\n  await cluster.sendCommand(false, 'CUSTOM_CMD', ['arg1', 'key1']);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('begin_search type')) {\n    // keyword-based key discovery — route manually\n  } else {\n    throw err;\n  }\n}","preventionTips":["Verify the command's key spec beginSearch type — standard multi_shard commands use 'index'","Do not tag keyword-based-begin_search commands 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"}