{"record":{"id":"ec8c47685176c140","repo":"redis/node-redis","slug":"cannot-split-label-malformed-numkeys-argument","errorCode":null,"errorMessage":"Cannot split ${label}: malformed numkeys argument '${args[keyNumIdx]}'","messagePattern":"Cannot split (.+?): malformed numkeys argument '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts","lineNumber":92,"sourceCode":"      // 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;\n      keyRegionEnd = args.length;\n      break;\n    }\n    case 'keynum': {\n      keyStep = findKeys.keyStep;\n      keyNumIdx = start + findKeys.keyNumIdx;\n      keyRegionStart = start + findKeys.firstKey;\n      if (keyNumIdx >= keyRegionStart) {\n        throw new Error(`Cannot split ${label}: numkeys argument inside the key region`);\n      }\n      const numKeys = parsePositiveInteger(args[keyNumIdx]);\n      if (numKeys === undefined) {\n        throw new Error(`Cannot split ${label}: malformed numkeys argument '${args[keyNumIdx]}'`);\n      }\n      keyRegionEnd = keyRegionStart + numKeys * keyStep;\n      break;\n    }\n    default:\n      throw new Error(`Cannot split ${label}: unsupported find_keys type '${findKeys.type}'`);\n  }\n\n  if (keyStep < 1) {\n    throw new Error(`Cannot split ${label}: invalid keystep ${keyStep}`);\n  }\n  if (keyRegionStart < 1 || keyRegionEnd > args.length) {\n    throw new Error(`Cannot split ${label}: key region overruns the arguments`);\n  }\n  const regionLength = keyRegionEnd - keyRegionStart;\n  if (regionLength <= 0 || regionLength % keyStep !== 0) {\n    throw new Error(`Cannot split ${label}: key region does not align with keystep ${keyStep}`);\n  }","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/redis/node-redis/blob/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/request-response-policies/multi-shard-splitter.ts#L74-L110","documentation":"Thrown by the multi-shard splitter for keynum-type findKeys specs when the argument at the numkeys position cannot be parsed as a positive integer. The splitter reads the numkeys value to determine how many key groups follow; a non-integer or non-positive value means the command arguments are malformed or the key spec points to the wrong position.","triggerScenarios":"A keynum-spec command where the caller passed a non-numeric, zero, or negative value at the numkeys position; a key spec with an incorrect keyNumIdx offset that points to a non-numkeys argument. No standard multi_shard command uses keynum (MSETX is curated out), so this fires only under metadata changes.","commonSituations":"Metadata regeneration tags a keynum command as multi_shard; custom command metadata with an incorrect keyNumIdx; malformed caller arguments for a keynum command.","solutions":["Verify the command arguments at the numkeys position are a valid positive integer","Check the key spec's keyNumIdx offset matches the actual numkeys argument position","Report the issue if a standard command triggers this"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// For keynum-spec commands, validate the numkeys argument is a\n// positive integer before relying on multi_shard splitting.\nfunction validateNumkeys(args: ReadonlyArray<string>, numkeysIdx: number): void {\n  const val = Number(args[numkeysIdx]);\n  if (!Number.isInteger(val) || val <= 0) {\n    throw new Error(`numkeys argument at position ${numkeysIdx} must be a positive integer`);\n  }\n}","typeGuard":"function isMalformedNumkeys(err: unknown): boolean {\n  return err instanceof Error && err.message.includes('malformed numkeys argument');\n}","tryCatchPattern":"try {\n  await cluster.sendCommand(false, 'CUSTOM_CMD', ['abc', 'key1']);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('malformed numkeys')) {\n    // caller passed a non-integer at the numkeys position — fix arguments\n  } else {\n    throw err;\n  }\n}","preventionTips":["Verify the numkeys argument position contains a valid positive integer","Check the key spec's keyNumIdx offset matches the actual numkeys argument position","Report the issue if a standard 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"}