redis/node-redis · error · Error

Cannot split : unsupported begin_search type

Error message

Cannot split ${label}: unsupported begin_search type '${beginSearch.type}'

What it means

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.

Solutions

  1. Verify the command's key spec in COMMAND DOCS — if it uses keyword begin_search, it should not be tagged multi_shard
  2. Report the issue if a standard multi_shard command triggers this
  3. If the command must be split, consider extending the splitter to support keyword-based begin_search
Defensive patterns

Strategy: try-catch

Type guard

function isUnsupportedBeginSearch(err: unknown): boolean {
  return err instanceof Error && err.message.includes('unsupported begin_search type');
}

Try / catch

try {
  await cluster.sendCommand(false, 'CUSTOM_CMD', ['arg1', 'key1']);
} catch (err) {
  if (err instanceof Error && err.message.includes('begin_search type')) {
    // keyword-based key discovery — route manually
  } else {
    throw err;
  }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of redis/node-redis@90fd0652bc (2026-08-11). Data as JSON: /api/errors/9286b6fe7ea39e48. Report an issue: GitHub.

Appendix: source

Thrown at packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts:61

  const label = args.length > 0 ? args[0].toString() : '<empty>';

  if (!keySpecs || keySpecs.length === 0) {
    throw new Error(`Cannot split ${label}: command has no key specification`);
  }
  // TODO(multi-spec): a command whose keys are interchangeable but
  // syntactically scattered (e.g. a fixed-position key plus a keyword-tail
  // list) could legitimately be multi_shard with several specs, and
  // multi-region reconstruction would be deterministic. No such command
  // exists, and specs alone cannot distinguish that shape from linked-operand
  // specs (GEORADIUS-like) where splitting is meaningless — so refuse until a
  // real command motivates multi-region support.
  if (keySpecs.length > 1) {
    throw new Error(`Cannot split ${label}: multiple key specifications are not supported`);
  }

  const { beginSearch, findKeys } = keySpecs[0];
  if (beginSearch.type !== 'index') {
    throw new Error(`Cannot split ${label}: unsupported begin_search type '${beginSearch.type}'`);
  }

  const start = beginSearch.index;
  let keyRegionStart: number;
  let keyRegionEnd: number;
  let keyStep: number;
  // Absolute position of the numkeys argument to rewrite per sub-command.
  let keyNumIdx: number | undefined;

  switch (findKeys.type) {
    case 'range': {
      // All current multi_shard range specs are "until end of args"; bounded
      // ranges (lastKey >= 0) and limit can be added when a command needs them.
      if (findKeys.lastKey !== -1 || findKeys.limit !== 0) {
        throw new Error(`Cannot split ${label}: unsupported find_keys range (lastkey ${findKeys.lastKey}, limit ${findKeys.limit})`);
      }
      keyStep = findKeys.keyStep;
      keyRegionStart = start;

View on GitHub (pinned to 90fd0652bc)