redis/node-redis · error · Error

Cannot split : numkeys argument inside the key region

Error message

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

What it means

Thrown by the multi-shard splitter for keynum-type findKeys specs when the numkeys argument position falls inside the key region. The numkeys argument must precede the keys so the splitter can rewrite it per sub-command (each sub-command's numkeys reflects only its own group count). If numkeys is inside the key region, rewriting it would overwrite a key, making the split ambiguous.

Solutions

1. This indicates a malformed key spec in the command metadata — report the issue
2. Verify the command's key spec layout: numkeys must be at a lower index than firstKey
3. Do not manually tag keynum-spec commands as multi_shard without verifying the spec layout

function isNumkeysInKeyRegion(err: unknown): boolean {
  return err instanceof Error && err.message.includes('numkeys argument inside the key region');
}

try {
  await cluster.sendCommand(false, 'CUSTOM_CMD', ['3', 'key1', 'key2', 'key3']);
} catch (err) {
  if (err instanceof Error && err.message.includes('numkeys argument inside')) {
    // malformed key spec metadata — report
  } else {
    throw err;
  }
}

When it happens

Trigger: A keynum key spec where keyNumIdx >= keyRegionStart; corrupted or malformed key spec metadata where the numkeys position overlaps with keys. This is a metadata integrity violation, not a caller error.

Common situations: No standard multi_shard command uses keynum specs (MSETX is curated out of multi_shard). This would fire only if metadata changes tag a keynum-spec command as multi_shard with an invalid spec layout.

Related errors

• Cannot split : command has no key specification
• Cannot split : malformed numkeys argument
• Cannot split : multiple key specifications are not supported
• Cannot split : unsupported begin_search type
• Cannot split : unsupported find_keys range (lastkey , limit…

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

Appendix: 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 90fd0652bc)