ERR max number of clients reached

What it means

Redis allows at most maxclients connections at once: 10,000 by default. When they’re all in use, it accepts each new connection only long enough to send this error, then closes it:

ERR max number of clients reached

Your client reads it as the reply to the first thing it sends (AUTH, HELLO, PING), and the connection is gone. Nothing is wrong with your password or the network; there’s no room.

Two things make it worse than it looks:

• No slot is kept back for administrators. In the test below, a connection as the default user, which may run every command, was refused like any other. To look inside, you first have to free a connection.
• The real limit may be lower than maxclients. Redis needs a file descriptor per connection plus 32 for itself. If the process’s open-files limit is lower, Redis lowers maxclients at startup and logs it, for example maxclients has been reduced to 992 to compensate for low ulimit.

On a cluster node, the cluster’s own links count too, and the message reads ERR max number of clients + cluster connections reached.

Common causes

1. Connection leaks: code that opens a new client per request or job and never closes it.
2. Pools larger than the server allows. Fifty application instances with a pool of 200 each can open 10,000 connections. Autoscaling and serverless functions multiply this.
3. Idle connections that never time out. timeout is 0 by default, so Redis never closes an idle client by itself.
4. Blocked and subscribed clients: each worker waiting in BLPOP, each SUBSCRIBE, holds a connection for as long as it waits.
5. A low open-files limit (ulimit -n, a systemd LimitNOFILE, Docker’s --ulimit nofile), which quietly lowers maxclients.
6. A fixed limit on a managed service. On AWS ElastiCache, maxclients is 65,000 on most node types and lower on small ones (20,000 on cache.t4g.micro), and can’t be changed.

How to fix it

Get a connection free

Stop or restart the application that holds the most connections (you’ll see which below once you’re in); that closes its connections. Or wait: as soon as one connection closes, the next new one gets in.

See who holds the connections

redis-cli INFO clients
redis-cli CLIENT LIST

INFO clients gives connected_clients, blocked_clients and maxclients; INFO stats counts the refusals in rejected_connections. CLIENT LIST has a line per connection:

id=16 addr=127.0.0.1:57740 laddr=127.0.0.1:6379 fd=22 name=worker-1 age=4 idle=4 flags=N db=0 …

Group the lines by the IP part of addr (the client machine), name (set with CLIENT SETNAME) or lib-name. Many connections from one place with a large idle are a pool or a leak; a large age and growing count suggests a leak.

Close what shouldn’t be there

redis-cli CLIENT KILL ADDR <ip:port>
redis-cli CLIENT KILL USER <user>
redis-cli CLIENT KILL MAXAGE 3600     # Redis 7.4 or later: older than an hour

This buys time; the application opens them again if the cause is still there.

Close idle connections automatically

redis-cli CONFIG SET timeout 300

Redis then closes normal clients idle for more than 300 seconds (not Pub/Sub subscribers). Make sure your pools cope with a connection closed under them, or give them an idle timeout shorter than this.

Fix the pools and the leaks

Use one client (one pool) per process and share it, rather than one per request. Add up the pool maximum across every instance of every application and keep it well below maxclients. Name your connections (CLIENT SETNAME, or your library’s client name setting) so CLIENT LIST tells you who they belong to next time.

Raise the limit, if the load is real

redis-cli CONFIG SET maxclients 20000

Raise the open-files limit first, or Redis can’t use the extra connections: LimitNOFILE in the systemd unit, ulimit -n for a server started by hand, --ulimit nofile=<n>:<n> for Docker. Then put maxclients in redis.conf so it survives a restart.

Reproduce it

A temporary Redis 8.10.2 container started with --maxclients 2, with two connections held open (named worker-1 and worker-2). A third connection:

$ redis-cli PING
(error) ERR max number of clients reached

A fourth, as the default user (redis-cli --user default INFO clients), got the same error. Once the two had closed, INFO stats showed rejected_connections:2. With the limit raised to 4 and one worker connected, CLIENT LIST showed it by name (above), and CLIENT KILL MAXAGE 2 returned (integer) 1.

A temporary container started with --ulimit nofile=1024:1024 and the default maxclients logged:

# 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: Operation not permitted.
# Current maximum open files is 1024. maxclients has been reduced to 992 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'.

and CONFIG GET maxclients returned 992.

A cluster-enabled Redis 8.10.2 node with --maxclients 1 and one connection held:

(error) ERR max number of clients + cluster connections reached

Valkey 8.1.10 with --maxclients 1 gave (error) ERR max number of clients reached, the same as Redis.

In Inlet

When the server turns Inlet away while it signs in, Inlet reports:

Couldn’t sign in: max number of clients reached

and links the error to this page. Once you’re connected, Activity lists the server’s clients and can kill them, and INFO clients and CLIENT LIST in a query tab show as tables, which makes it easier to see which application holds the connections.