redis/node-redis · error · Error

Unsupported reply type for merge aggregation

Error message

Unsupported reply type for merge aggregation

What it means

Thrown by aggregateMerge when the first shard's reply is not an array, Map, or plain object. This reducer is used by the default_keyless response policy for fan-out commands (e.g. KEYS under all_shards) and by the special-policy fallback. It merges arrays (union via Set), Maps (last-node-wins per key), and plain objects (Object.assign). Any other reply type (string, number, boolean, null) cannot be merged.

Solutions

1. Identify the command triggering the merge and verify its reply shape is a collection (array, Map, or object) under fan-out
2. If the command returns scalars, use a different approach (e.g. route to a single node, or use sendCommand with a custom aggregation)
3. For special-policy commands, check whether a dedicated reducer should be registered

function isMergeAggError(err: unknown): boolean {
  return err instanceof Error && err.message.includes('merge aggregation');
}

try {
  await cluster.sendCommand(true, 'KEYS', '*');
} catch (err) {
  if (err instanceof Error && err.message.includes('merge aggregation')) {
    // fan-out reply was not a collection type — route to single node instead
    const nodes = cluster.nodes('master');
    const results = await Promise.all(nodes.map(n => n.keys('*')));
  } else {
    throw err;
  }
}

When it happens

Trigger: A fan-out command under default_keyless or special response policy where shards return scalar replies — e.g. a command that returns a string or number on each node being routed all_shards with default_keyless merging. The special-policy fallback also hits this when a command has no dedicated reducer and its shard replies are scalars.

Common situations: Calling a command with all_shards routing that returns scalar replies per node; a command tagged 'special' response with no registered per-command reducer whose replies are not collection types.

Related errors

• All replies must be array of numbers for logical AND…
• All replies must be array of numbers for logical OR…
• All replies must be number arrays of equal length for
• All replies must be numbers for max aggregation
• All replies must be numbers for min aggregation

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

Appendix: source

Thrown at packages/client/lib/cluster/request-response-policies/generic-aggregators.ts:196

		for(const reply of replies) {
			for(const [key, value] of reply as Map<unknown, unknown>) {
				map.set(key, value);
			}
		}
		return map as T;
	}

	// RESP3 map replies decode to plain objects under the default type
	// mapping; merge them like the Map branch (last node wins per key).
	if(typeof firstReply === 'object' && firstReply !== null) {
		const merged: Record<string, unknown> = {};
		for(const reply of replies) {
			Object.assign(merged, reply);
		}
		return merged as T;
	}

	throw new Error('Unsupported reply type for merge aggregation');

};

View on GitHub (pinned to 90fd0652bc)