DevSecOps

Redis Connection Errors: Complete Troubleshooting Guide

DeviDevs Team
••6 min read
#redis#caching#troubleshooting#database#devops

Redis connection issues can cripple application performance. This guide covers all common Redis errors and their solutions.

Error: ECONNREFUSED - Connection Refused

Symptom:

Error: connect ECONNREFUSED 127.0.0.1:6379
Redis connection to localhost:6379 failed - connect ECONNREFUSED

Solution 1 - Verify Redis is running:

# Check Redis status
sudo systemctl status redis
 
# Start Redis
sudo systemctl start redis
 
# Docker
docker ps | grep redis
docker start redis-container
 
# Test connection
redis-cli ping
# Should return: PONG

Solution 2 - Check Redis binding:

# Check what Redis is listening on
sudo netstat -tlnp | grep 6379
# or
ss -tlnp | grep 6379
 
# Edit redis.conf
sudo nano /etc/redis/redis.conf
 
# Change bind to allow connections
# bind 127.0.0.1       # localhost only
bind 0.0.0.0           # all interfaces (be careful in production!)
 
# Restart Redis
sudo systemctl restart redis

Solution 3 - Docker networking:

# docker-compose.yml
services:
  app:
    environment:
      - REDIS_HOST=redis  # Use service name, not localhost
    depends_on:
      - redis
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Error: NOAUTH Authentication Required

Symptom:

NOAUTH Authentication required
Error: ERR invalid password
ReplyError: WRONGPASS invalid username-password pair

Solution 1 - Provide password:

// Node.js with ioredis
const Redis = require('ioredis');
const redis = new Redis({
  host: 'localhost',
  port: 6379,
  password: 'your-password'
});
 
// Connection URL format
const redis = new Redis('redis://:your-password@localhost:6379');
 
// With username (Redis 6+)
const redis = new Redis('redis://username:password@localhost:6379');
# Python
import redis
r = redis.Redis(
    host='localhost',
    port=6379,
    password='your-password',
    decode_responses=True
)

Solution 2 - Verify password in redis.conf:

# Check current password
grep "requirepass" /etc/redis/redis.conf
 
# Set password
requirepass your-strong-password
 
# For Redis 6+ ACL
# redis-cli
ACL SETUSER default on >password ~* &* +@all

Solution 3 - Reset password:

# Connect without auth (if possible)
redis-cli
 
# Set new password
CONFIG SET requirepass "new-password"
 
# Persist change
CONFIG REWRITE

Error: Max Number of Clients Reached

Symptom:

ERR max number of clients reached
OOM command not allowed when used memory > 'maxmemory'

Solution 1 - Increase max clients:

# Check current setting
redis-cli CONFIG GET maxclients
 
# Increase limit (requires redis.conf or CONFIG SET)
maxclients 10000
 
# Check current connections
redis-cli INFO clients

Solution 2 - Find connection leaks:

# List all connected clients
redis-cli CLIENT LIST
 
# Find long-idle connections
redis-cli CLIENT LIST | grep "idle=[0-9][0-9][0-9][0-9]"
 
# Kill specific client
redis-cli CLIENT KILL ID <client-id>
 
# Set client timeout
timeout 300  # 5 minutes

Solution 3 - Use connection pooling:

// ioredis connection pool
const Redis = require('ioredis');
 
const redis = new Redis({
  host: 'localhost',
  port: 6379,
  maxRetriesPerRequest: 3,
  enableOfflineQueue: false,
  lazyConnect: true,
  // Connection pool (via cluster for single node)
  family: 4,
  keepAlive: 10000
});
# Python connection pool
import redis
 
pool = redis.ConnectionPool(
    host='localhost',
    port=6379,
    max_connections=50,
    password='your-password'
)
 
r = redis.Redis(connection_pool=pool)

Error: Connection Timeout

Symptom:

Error: Connection timeout
ETIMEDOUT: connection timed out
Redis connection lost. Reconnecting...

Solution 1 - Increase timeouts:

const Redis = require('ioredis');
 
const redis = new Redis({
  host: 'localhost',
  port: 6379,
  connectTimeout: 10000,    // 10 seconds
  commandTimeout: 5000,     // 5 seconds per command
  retryDelayOnFailover: 100,
  retryDelayOnClusterDown: 100,
  maxRetriesPerRequest: 3
});

Solution 2 - Check network latency:

# Test latency
redis-cli --latency
 
# Intrinsic latency (server-side)
redis-cli --intrinsic-latency 10
 
# Debug slowlog
redis-cli SLOWLOG GET 10

Solution 3 - Configure TCP keepalive:

# redis.conf
tcp-keepalive 300
 
# Application-side
const redis = new Redis({
  keepAlive: 10000,  // 10 seconds
  noDelay: true
});

Error: READONLY - Replica Mode

Symptom:

READONLY You can't write against a read only replica
Error: READONLY

Cause: Connected to a replica instead of primary.

Solution 1 - Connect to primary:

# Find primary
redis-cli INFO replication
 
# Look for:
# role:master (this is primary)
# role:slave (this is replica)
// Sentinel for automatic failover
const redis = new Redis({
  sentinels: [
    { host: 'sentinel-1', port: 26379 },
    { host: 'sentinel-2', port: 26379 }
  ],
  name: 'mymaster'
});

Solution 2 - Enable writes on replica (temporary):

# Not recommended for production
redis-cli CONFIG SET replica-read-only no

Error: Cluster Connection Issues

Symptom:

CLUSTERDOWN The cluster is down
MOVED 12345 192.168.1.100:6379
ASK 12345 192.168.1.101:6379

Solution 1 - Use cluster-aware client:

// ioredis cluster mode
const Redis = require('ioredis');
 
const cluster = new Redis.Cluster([
  { host: '192.168.1.100', port: 6379 },
  { host: '192.168.1.101', port: 6379 },
  { host: '192.168.1.102', port: 6379 }
], {
  redisOptions: {
    password: 'cluster-password'
  },
  scaleReads: 'slave',
  natMap: {
    // If behind NAT/proxy
    '10.0.0.1:6379': { host: 'public-host', port: 6379 }
  }
});

Solution 2 - Check cluster health:

# Cluster info
redis-cli CLUSTER INFO
 
# Cluster nodes
redis-cli CLUSTER NODES
 
# Fix cluster
redis-cli --cluster fix 192.168.1.100:6379

Error: Out of Memory

Symptom:

OOM command not allowed when used memory > 'maxmemory'
-OOM: Redis is out of memory

Solution 1 - Configure memory policy:

# redis.conf
maxmemory 2gb
maxmemory-policy allkeys-lru
 
# Available policies:
# noeviction - return errors
# allkeys-lru - evict least recently used
# volatile-lru - evict LRU among keys with TTL
# allkeys-random - evict random keys
# volatile-ttl - evict keys with shortest TTL

Solution 2 - Monitor memory usage:

# Memory stats
redis-cli INFO memory
 
# Memory usage by key pattern
redis-cli --bigkeys
 
# Memory usage of specific key
redis-cli MEMORY USAGE mykey

Solution 3 - Clean up:

# Delete keys by pattern
redis-cli --scan --pattern "temp:*" | xargs redis-cli DEL
 
# Flush database (careful!)
redis-cli FLUSHDB  # Current DB
redis-cli FLUSHALL # All DBs

Reconnection Strategy

const Redis = require('ioredis');
 
const redis = new Redis({
  host: 'localhost',
  port: 6379,
  retryStrategy(times) {
    if (times > 10) {
      // Stop retrying after 10 attempts
      return null;
    }
    // Exponential backoff: 50ms, 100ms, 200ms...
    const delay = Math.min(times * 50, 2000);
    return delay;
  },
  reconnectOnError(err) {
    const targetError = 'READONLY';
    if (err.message.includes(targetError)) {
      // Reconnect when replica becomes primary
      return true;
    }
    return false;
  }
});
 
redis.on('error', (error) => {
  console.error('Redis error:', error);
});
 
redis.on('connect', () => {
  console.log('Redis connected');
});
 
redis.on('reconnecting', () => {
  console.log('Redis reconnecting...');
});

Quick Reference: Debug Commands

| Task | Command | |------|---------| | Test connection | redis-cli PING | | Check info | redis-cli INFO | | Memory stats | redis-cli INFO memory | | Client list | redis-cli CLIENT LIST | | Slow queries | redis-cli SLOWLOG GET 10 | | Latency | redis-cli --latency | | Big keys | redis-cli --bigkeys | | Cluster status | redis-cli CLUSTER INFO |

Redis Performance at Scale?

High-performance Redis deployments require careful tuning. Our team offers:

  • Redis cluster architecture design
  • Memory optimization strategies
  • High-availability configuration
  • Performance monitoring setup

Get Redis expertise

Weekly AI Security & Automation Digest

Get the latest on AI Security, workflow automation, secure integrations, and custom platform development delivered weekly.

No spam. Unsubscribe anytime.

Related Articles

DevSecOps

GitHub Actions: Common CI/CD Errors and How to Fix Them

Troubleshoot GitHub Actions errors including permission denied, checkout failures, secret exposure, artifact issues, and workflow timeout fixes with practical solutions.

•6 min read
DevSecOps

Kubernetes CrashLoopBackOff: Complete Troubleshooting Guide

Fix Kubernetes CrashLoopBackOff errors including OOMKilled, failed health checks, missing secrets, image pull errors, and configuration issues with step-by-step solutions.

•6 min read
DevSecOps

Terraform State Lock Errors: How to Fix and Prevent Them

Troubleshoot Terraform state lock errors including lock acquisition failed, state file locked, DynamoDB errors, and S3 backend issues with safe unlock procedures.

•6 min read
← Back to Blog