How to fix ERR Unbalanced XREAD list of streams in Redis

Check that you're providing equal numbers of stream keys and stream IDs. The correct syntax is:

XREAD STREAMS stream_key1 stream_key2 stream_id1 stream_id2

For a single stream reading new messages:

XREAD STREAMS mystream $

For multiple streams:

XREAD STREAMS stream1 stream2 stream3 0-0 0-0 0-0

Ensure you have exactly one ID for each stream key listed.

If using a Redis client library, verify you're passing the IDs parameter correctly. Different libraries have different APIs:

Node.js (node-redis):

await client.xRead(
  { key: 'mystream', id: '0-0' },
  { BLOCK: 5000 }
);

Go (go-redis):

streams, err := client.XRead(ctx, &redis.XReadArgs{
    Streams: []string{"mystream", "0-0"}, // Key first, then ID
    Count:   10,
    Block:   0,
}).Result()

Python (redis-py):

client.xread({'mystream': '0-0'}, count=10)

Consult your specific client library documentation for the correct parameter structure.

Redis supports special ID values for different reading behaviors:

- $ - Read only new entries (ones added after this command)
- > - For XREADGROUP only, get messages never delivered to any consumer
- 0-0 - Read from the beginning of the stream
- Specific ID - Start reading after a particular entry (e.g., "1609459200000-0")

Example using $ to read new messages:

XREAD BLOCK 0 STREAMS notifications $

For XREADGROUP:

XREADGROUP GROUP mygroup consumer1 STREAMS mystream >

When reading from multiple streams, ensure you provide IDs in the same order as the keys:

# Correct - 3 streams, 3 IDs
XREAD STREAMS orders payments notifications $ $ $

# Correct - mix of IDs
XREAD STREAMS stream1 stream2 1609459200000-0 $

# Wrong - 3 streams, only 2 IDs (causes error)
XREAD STREAMS orders payments notifications $ $

Each stream must have a corresponding ID, even if you use the same special marker for all of them.

Some older versions of Redis client libraries had bugs in XREAD/XREADGROUP implementations. Check if you're using an outdated version:

# Node.js
npm outdated redis

# Python
pip list --outdated | grep redis

# Go
go list -m -u github.com/redis/go-redis/v9

Update to the latest stable version:

# Node.js
npm install redis@latest

# Python
pip install --upgrade redis

# Go
go get -u github.com/redis/go-redis/v9

Review the changelog for XREAD-related fixes.