How to fix ERR max number of clients reached in Redis

RedisINTERMEDIATEHIGHUpdated Dec 29, 2025· 183 views

Redis has hit its maximum client connection limit. Increase the maxclients configuration, fix connection leaks in your application, or use connection pooling to resolve this error.

Quick fix

Fixes ERR max number of clients reached

redis-cli config get maxclients
  1. Check current maxclients setting
  2. Increase maxclients via Redis CLI
  3. Make the change permanent in redis.conf
  4. Increase system file descriptor limits
redis — error
redis-cli config get maxclients
ERR max number of clients reached

What this error means

This error occurs when the number of active client connections to your Redis server exceeds the configured maximum limit. Redis has a configurable `maxclients` setting (default 10,000) that prevents too many simultaneous connections to avoid resource exhaustion. When a new client attempts to connect and this limit is reached, Redis refuses the connection and returns this error. The actual limit is also constrained by operating system file descriptor limits.

Typical symptoms

  • Application fails to connect to Redis with connection refused errors
  • Redis CLI commands fail with "max number of clients reached" message
  • Intermittent connection failures that worsen over time
  • New requests fail while some existing connections remain active
  • Error appears after application uptime increases or during peak load

Common causes

  1. maxclients configuration too low for application workload
  2. Connection leaks from missing close/disconnect statements in application code
  3. Client library creating new connections without proper pooling
  4. Managed Redis service plan with insufficient connection allowance
  5. Operating system file descriptor limits preventing Redis from handling configured maxclients
  6. Application not reusing connections from connection pool effectively

How to fix "ERR max number of clients reached"

1Check current maxclients setting

Connect to Redis and view the current limit:

bash
redis-cli config get maxclients

This will show your current setting. The default is 10,000.

2Increase maxclients via Redis CLI

Increase the limit at runtime using:

bash
redis-cli config set maxclients 50000

Replace 50000 with your desired limit. This takes effect immediately but will not persist after Redis restart.

3Make the change permanent in redis.conf

Edit your Redis configuration file (usually /etc/redis/redis.conf) and find the maxclients directive:

conf
maxclients 50000

Uncomment or modify the line to your desired value, then save the file.

4Increase system file descriptor limits

Redis needs sufficient file descriptors at the OS level. Check and increase the limit:

bash
ulimit -n
ulimit -Sn 100000

For permanent changes, edit /etc/systemd/system/redis.service:

ini
[Service]
LimitNOFILE=100000

Then reload and restart:

bash
sudo systemctl daemon-reload
sudo systemctl restart redis
5Restart Redis to apply permanent changes

After editing redis.conf, restart the Redis service:

bash
sudo systemctl restart redis

Or if using Docker:

bash
docker restart <container_id>
6Fix connection leaks in your application

Review your application code for missing connection cleanup. Ensure all Redis connections are properly closed:

Node.js/TypeScript:

typescript
const redis = require('redis');
const client = redis.createClient();

try {
  // Use client
} finally {
  await client.quit(); // Explicitly close
}

Python:

python
import redis
client = redis.Redis()
try:
    # Use client
finally:
    client.close()

Go:

go
client := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
defer client.Close()
7Implement connection pooling

Use connection pooling to reuse connections instead of creating new ones:

Node.js with redis-pool:

typescript
const pool = new Pool({
  max: 20,
  min: 5,
  idleTimeoutMillis: 30000
});

Python with redis-py:

python
from redis import ConnectionPool, Redis
pool = ConnectionPool.from_url('redis://localhost')
client = Redis(connection_pool=pool)

Advanced notes

Redis 7.0+ includes client eviction, a safety mechanism that automatically disconnects clients consuming the most memory when aggregate client memory exceeds a threshold. You can configure timeout settings to automatically close idle connections: CONFIG SET timeout 300 (300 seconds). For managed Redis services (Heroku, AWS ElastiCache, Google Cloud Memorystore, etc.), the maxclients limit is often determined by your plan tier. Upgrading your plan may be necessary if you consistently need more connections. When calculating required connections, account for application instances, background workers, and monitoring tools. For example, 20 application pods × 50 connections per pod = 1,000 total connections needed.

Frequently asked questions

What does "ERR max number of clients reached" mean?
This error occurs when the number of active client connections to your Redis server exceeds the configured maximum limit. Redis has a configurable maxclients setting (default 10,000) that prevents too many simultaneous connections to avoid resource exhaustion. When a new client attempts to connect and this limit is reached, Redis refuses the connection and returns this error.
How do I fix "ERR max number of clients reached"?
Redis has hit its maximum client connection limit. Increase the maxclients configuration, fix connection leaks in your application, or use connection pooling to resolve this error.
What causes "ERR max number of clients reached"?
maxclients configuration too low for application workload Connection leaks from missing close/disconnect statements in application code Client library creating new connections without proper pooling
Is the "ERR max number of clients reached" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading