🚨 Redis Error Guide: 'ERR max number of clients reached' — Connection Limit Hit

Overview

ERR max number of clients reached is returned when a new connection tries to attach but Redis already has as many connected clients as its maxclients limit allows. Redis rejects the connection immediately rather than degrading — so the very act of connecting fails, before any command runs. Effective maxclients is also capped by the process file-descriptor limit (ulimit -n): Redis reserves 32 FDs for internal use and lowers maxclients at startup if the OS limit is too low.

The literal error a client receives:

(error) ERR max number of clients reached

You may also see it in a client stack trace as redis.exceptions.ConnectionError: max number of clients reached. It typically means either a genuine surge of connections, or — far more often — leaked/unpooled connections that never close.

Symptoms

• New clients fail to connect with max number of clients reached while existing connections keep working.
• INFO clients shows connected_clients at or near maxclients.
• Error rate correlates with deploys, autoscaling events, or long-running batch jobs.
• Startup log warns that maxclients was reduced due to a low FD limit.

redis-cli INFO clients | grep -E 'connected_clients|maxclients|blocked'

connected_clients:10000
maxclients:10000
blocked_clients:0

Common Root Causes

1. Connection leak / no pooling

The most common cause: application code opens a new connection per request (or per worker) and never closes it, instead of using a bounded connection pool. Connection count climbs monotonically until the ceiling.

redis-cli CLIENT LIST | awk '{print $NF}' | sort | uniq -c | sort -rn | head
redis-cli CLIENT LIST | grep -oE 'addr=[0-9.]+' | sort | uniq -c | sort -rn | head

   4021 addr=10.0.3.11
   3980 addr=10.0.3.12

Thousands of connections from one host almost always means a leak or oversized pool.

2. maxclients set too low for the workload

Default is 10000. A large fleet with generous per-instance pools can legitimately exceed it.

redis-cli CONFIG GET maxclients

# redis.conf
maxclients 10000

3. Low OS file-descriptor limit clamps maxclients

If ulimit -n is small, Redis silently lowers maxclients at boot.

cat /proc/$(pgrep -o redis-server)/limits | grep 'open files'
redis-cli CONFIG GET maxclients   # may be far below what you configured

Max open files            1024                 1024                 files

Startup log:

You requested maxclients of 10000 requiring at least 10032 max file descriptors.
Server can't set maximum open files to 10032 because of OS error.
Current maximum open files is 1024. maxclients has been reduced to 992.

4. Idle / stale connections not reaped

Without a client timeout, dropped-but-not-closed sockets linger and consume slots.

redis-cli CONFIG GET timeout
redis-cli CLIENT LIST | grep -oE 'idle=[0-9]+' | sort -t= -k2 -n | tail

Diagnostic Workflow

Step 1: Confirm you’re actually at the limit

redis-cli INFO clients
redis-cli CONFIG GET maxclients

If connected_clients == maxclients, the error is genuine — not a network blip.

Step 2: Find where connections come from

redis-cli CLIENT LIST > /tmp/clients.txt
awk -F'addr=' '{print $2}' /tmp/clients.txt | awk '{print $1}' | \
  cut -d: -f1 | sort | uniq -c | sort -rn | head
grep -oE 'name=[^ ]+' /tmp/clients.txt | sort | uniq -c | sort -rn | head

Group by source IP and name= (set via CLIENT SETNAME) to identify the leaking service.

Step 3: Check the OS FD ceiling

cat /proc/$(pgrep -o redis-server)/limits | grep 'open files'
journalctl -u redis 2>/dev/null | grep -i 'maxclients has been reduced'

Step 4: Immediate relief — reap and raise

# Kill connections idle longer than 1 hour from a leaking host
redis-cli CLIENT LIST | awk -F'[= ]' '/idle/ {for(i=1;i<=NF;i++) if($i=="idle" && $(i+1)>3600) print}'
redis-cli CLIENT KILL ADDR 10.0.3.11:0   # or by ID from CLIENT LIST
# Raise the runtime cap (also raise ulimit -n / systemd LimitNOFILE first)
redis-cli CONFIG SET maxclients 20000

CONFIG SET maxclients is not persisted — update redis.conf too.

Example Root Cause Analysis

After a deploy, the API tier began logging max number of clients reached. INFO clients showed connected_clients:10000 pinned at the cap. Grouping CLIENT LIST by address revealed 4000+ connections from each of three app hosts — far more than the configured pool of 50 per instance.

redis-cli CLIENT LIST | grep -c 'addr=10.0.3.11'

4021

The deploy had introduced a code path that created a fresh redis.Redis() client inside a request handler instead of reusing the module-level pool, leaking one connection per request. Immediate mitigation was to kill the idle connections and bump maxclients; the real fix was moving client creation to a shared, bounded pool and setting timeout 300 so orphaned sockets get reaped.

redis-cli CONFIG SET timeout 300
redis-cli CLIENT KILL ADDR 10.0.3.11:0

Connection count fell to ~150 and the errors stopped.

Prevention Best Practices

• Always use a bounded connection pool; never open a connection per request. Cap pool size × instance count well below maxclients.
• Set timeout in redis.conf (e.g. timeout 300) to reap idle/dead connections.
• Size maxclients for peak fleet size, and raise the OS limit to match via systemd LimitNOFILE and ulimit -n.
• Name connections with CLIENT SETNAME so CLIENT LIST attributes leaks to a service.
• Alert on connected_clients approaching maxclients (e.g. >80%).
• See related Redis error guides for connection-reset and latency issues.

Quick Command Reference

# Are we at the limit?
redis-cli INFO clients | grep -E 'connected_clients|maxclients'
redis-cli CONFIG GET maxclients

# Who is connecting?
redis-cli CLIENT LIST | awk -F'addr=' '{print $2}' | awk '{print $1}' | \
  cut -d: -f1 | sort | uniq -c | sort -rn | head

# OS FD ceiling
cat /proc/$(pgrep -o redis-server)/limits | grep 'open files'

# Immediate relief
redis-cli CLIENT KILL ADDR <ip:port>
redis-cli CONFIG SET maxclients 20000
redis-cli CONFIG SET timeout 300

Conclusion

ERR max number of clients reached means Redis has hit maxclients (or an FD-clamped lower value) and is refusing new connections. The usual culprits:

1. A connection leak or missing/oversized pool driving connected_clients ever upward.
2. maxclients set too low for a large fleet.
3. A low ulimit -n silently reducing maxclients at startup.
4. Idle/stale connections never reaped because timeout is 0.

Start with INFO clients and group CLIENT LIST by source to find the leak, reap idle connections and raise the cap for immediate relief, then fix pooling and FD limits so it does not recur.