redis/node-redis · error · Error

Cannot split ${label}: unsupported begin_search type '${begi

Error message

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

What it means

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.

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 bb5beb5657)

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.

Defensive patterns

Strategy: try-catch

Type guard

function isIndexBeginSearch(spec: unknown): spec is { type: 'index'; index: number } {
  return typeof spec === 'object' && spec !== null && (spec as { type?: string }).type === 'index';
}

Try / catch

try {
  await cluster.del('k1', 'k2');
} catch (e) {
  if (/unsupported begin_search type/.test(e.message)) {
    // spec is keyword/unknown — re-tag command or regenerate metadata
  } else throw e;
}

Prevention

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.

When it happens

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

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

Related errors

AI-assisted analysis of redis/node-redis@bb5beb5657 (2026-08-03). Data as JSON: /data/errors/9286b6fe7ea39e48.json. Report an issue: GitHub.