How to fix ERR max number of clients reached in Redis

RedisINTERMEDIATEHIGH

The "ERR max number of clients reached" error occurs when the number of active client connections exceeds Redis's configured maxclients limit (default 10,000). Common causes include connection leaks, insufficient connection pooling, and undersized Redis instances. Fix by using connection pooling, increasing maxclients, upgrading your Redis instance, or reducing connection usage.

What this error means

Redis has a built-in limit on the maximum number of simultaneous client connections it accepts. When a new client tries to connect and the server has already reached this limit, the connection is immediately rejected with "ERR max number of clients reached". The default maxclients limit in Redis 2.6+ is 10,000 connections. However, managed Redis services (Heroku, Redis Cloud, AWS ElastiCache) often have lower limits depending on your plan tier—mini plans may allow only 20 clients, while premium tiers support thousands. When the limit is hit, no new connections can be established until existing connections are closed. This error is a critical signal that your application is either creating too many connections, not properly closing connections (connection leak), or your Redis instance is undersized for your workload. It requires immediate attention as it prevents new requests from accessing the database.

How to fix "ERR max number of clients reached"

1Check current client connection count using Redis INFO command

First, understand how many connections are currently active to identify the severity.

bash

# Connect to Redis CLI:
redis-cli

# Check current connections:
INFO clients

# Look for the "connected_clients" field. Example output:
# connected_clients:15243
# blocked_clients:2
# maxclients:10000

If connected_clients is at or very close to maxclients, you've hit the limit. If it's consistently high (>80% of maxclients), action is needed even if you haven't hit the hard limit yet.

2Identify which applications or services are holding connections

Use the CLIENT command to list all connections and identify heavy consumers.

bash

# List all connected clients:
redis-cli CLIENT LIST

# Get a summary:
redis-cli CLIENT LIST | wc -l

# Filter by specific source:
redis-cli CLIENT LIST | grep "addr=<IP_ADDRESS>"

Look for patterns:
- Too many connections from a single server (indicates undersized pool or no pooling)
- Many "idle" connections stuck waiting for operations
- Connections with large "buf" values (buffered output, slow clients)

3Implement or optimize connection pooling on your application

Connection pooling reuses connections instead of creating new ones for each request.

Node.js example with ioredis:

javascript

const Redis = require("ioredis");
const redis = new Redis({
  host: "localhost",
  port: 6379,
  maxRetriesPerRequest: null,
  enableReadyCheck: false,
  // Pool settings to limit total connections:
  // Reuse connections across requests
});

// Reuse the same redis instance across your app
module.exports = redis;

Ruby/Rails example:

ruby

# config/initializers/redis.rb
REDIS = Redis.new(
  url: ENV["REDIS_URL"],
  pool: { size: 10, timeout: 5 }  # Limit to 10 connections
)

Python example:

python

from redis import ConnectionPool, Redis

pool = ConnectionPool.from_url(
    "redis://localhost:6379",
    max_connections=20  # Limit total connections
)
redis_client = Redis(connection_pool=pool)

For queue processors (Sidekiq, Bull, Resque), ensure you've configured the concurrency and pool size appropriately.

4Increase the maxclients limit if pooling is already optimized

If you've confirmed pooling is correct but still need more capacity, increase maxclients.

bash

# Check current limit:
redis-cli CONFIG GET maxclients

# Increase it at runtime (survives until next restart):
redis-cli CONFIG SET maxclients 20000

# Verify the change:
redis-cli CONFIG GET maxclients

For persistent configuration, edit your redis.conf:

bash

# /etc/redis/redis.conf
maxclients 20000

Then restart Redis:

bash

sudo systemctl restart redis-server

Important: Increasing maxclients also requires sufficient OS file descriptor limits. Check: ulimit -n (should be higher than maxclients).

5Check and increase OS file descriptor limits if needed

Redis can't accept more connections than the OS allows. File descriptors must exceed maxclients.

bash

# Check current file descriptor limit:
ulimit -n

# For root/Redis service, check:
cat /proc/sys/fs/file-max

Increase if needed:

bash

# Temporary (until reboot):
ulimit -n 65536

# Permanent (edit /etc/security/limits.conf):
echo "redis soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "redis hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# Apply changes:
sudo sysctl -p

For systemd services, edit /etc/systemd/system/redis.service.d/override.conf:

bash

[Service]
LimitNOFILE=65536

Then reload and restart:

bash

sudo systemctl daemon-reload
sudo systemctl restart redis-server

6Upgrade your Redis instance if hitting limits on managed services

For hosted Redis services (Heroku, Redis Cloud, AWS ElastiCache), plans have hard limits.

bash

# Check which plan you're on:
# Heroku:
heroku redis:info

# AWS ElastiCache:
aws elasticache describe-cache-clusters --cache-cluster-id my-redis

If you're consistently at or near your plan's connection limit:
- Upgrade to a larger tier (premium plans support more connections)
- Switch providers if current rates are uneconomical
- Consider read replicas or cluster mode to scale horizontally

Migration example for Heroku:

bash

# Provision larger Redis instance
heroku addons:create heroku-redis:premium-2

# Update your app to use new instance
# Deploy and verify

How to fix ERR max number of clients reached in Redis

What this error means

Typical symptoms

Common causes

How to fix "ERR max number of clients reached"

Advanced notes

Related errors

Official resources & further reading