redis/node-redis · error · Error

Cannot split ${label}: numkeys argument inside the key regio

Error message

Cannot split ${label}: numkeys argument inside the key region

What it means

For `keynum` specs, the numkeys argument's position (beginSearch.index + findKeys.keyNumIdx) must come BEFORE the key region (beginSearch.index + findKeys.firstKey). If the spec places numkeys inside the key region, per-slot rewriting of numkeys would corrupt the key sequence, so the splitter refuses. This is a spec-invariant violation, not a user-argument error.

Source

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

  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;
      keyRegionEnd = args.length;
      break;
    }
    case 'keynum': {
      keyStep = findKeys.keyStep;
      keyNumIdx = start + findKeys.keyNumIdx;
      keyRegionStart = start + findKeys.firstKey;
      if (keyNumIdx >= keyRegionStart) {
        throw new Error(`Cannot split ${label}: numkeys argument inside the key region`);
      }
      const numKeys = parsePositiveInteger(args[keyNumIdx]);
      if (numKeys === undefined) {
        throw new Error(`Cannot split ${label}: malformed numkeys argument '${args[keyNumIdx]}'`);
      }
      keyRegionEnd = keyRegionStart + numKeys * keyStep;
      break;
    }
    default:
      throw new Error(`Cannot split ${label}: unsupported find_keys type '${findKeys.type}'`);
  }

  if (keyStep < 1) {
    throw new Error(`Cannot split ${label}: invalid keystep ${keyStep}`);
  }
  if (keyRegionStart < 1 || keyRegionEnd > args.length) {
    throw new Error(`Cannot split ${label}: key region overruns the arguments`);
  }

View on GitHub (pinned to bb5beb5657)

Solutions

Verify the command's keynum spec layout in metadata — keyNumIdx must precede firstKey.
Re-run metadata generation if the spec looks wrong.
Re-tag the command away from multi_shard if its layout cannot be split.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await cluster.sendCommand(cmd, ...args);
} catch (e) {
  if (/numkeys argument inside the key region/.test(e.message)) {
    // malformed keynum spec in metadata — regenerate or override
  } else throw e;
}

Prevention

Verify keynum specs in metadata place keyNumIdx before firstKey.
Re-run metadata generation if a keynum spec looks malformed.
Re-tag keynum commands away from multi_shard if their layout can't be split.

When it happens

Trigger: A command tagged multi_shard with a keynum spec where keyNumIdx resolves to a position at or after the key region start. No current shipped multi_shard command uses a keynum spec through this path (MSEDEX is curated OUT), so this is metadata/spec invariant only.

Common situations: A malformed or future keynum spec in metadata; a metadata regeneration capturing an unusual keynum layout.

Related errors

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