SelestL Solutions
Technology

How to Fix Redis Connection Refused Error 111 Fast

By SelestL • Published on
How to Fix Redis Connection Refused Error 111 Fast

Few operational alerts disrupt backend APIs and queue workers faster than the notorious ECONNREFUSED 127.0.0.1:6379 or Error 111: Connection refused. When your application encounters a sudden Redis connection refused failure, cache lookups stall, session validation collapses, and asynchronous background jobs pile up in limbo.

Unlike timeout errors where the network packet reaches the server but receives no timely response, a connection refused response is an explicit OS-level rejection generated by the operating system TCP stack. The kernel on the target machine received your SYN packet on port 6379 and immediately replied with an RST (reset) packet, indicating that either no process was listening on that socket, or network security rules intervened. Whether you manage Redis as a bare-metal systemd service, within a Docker compose cluster, or inside Kubernetes, this comprehensive engineering guide provides the exact commands, configuration audits, and architecture checks to diagnose and eliminate Error 111 permanently. For engineering teams maintaining production backend infrastructure and high-availability database clusters, understanding these socket mechanics is critical.

Step 1: Check the Redis Service Daemon Status

The most common root cause of Error 111 is simply that the Redis server daemon is not actively running. Redis may have crashed due to memory exhaustion, failed during a reboot, or terminated on an unhandled signal.

Execute the standard Redis service check on your Linux host:

# Check daemon state on Ubuntu / Debian / CentOS
sudo systemctl status redis-server
# Or on RHEL / CentOS variants
sudo systemctl status redis

# If inactive or dead, inspect recent error logs
sudo journalctl -u redis-server --no-pager -n 50

If the service failed, restart it and enable automatic boot persistence:

sudo systemctl restart redis-server
sudo systemctl enable redis-server

Warning: Linux Kernel Overcommit Settings

If your journal logs display Can't save in background: fork: Cannot allocate memory, Redis crashed because Linux refused to allocate memory for the background RDB snapshot. Fix this instantly by executing sudo sysctl vm.overcommit_memory=1 and appending vm.overcommit_memory = 1 to /etc/sysctl.conf.

Step 2: Verify the Socket Binding and Listening Port

Even if the daemon is active, Redis will refuse inbound connections if it is bound to the wrong network interface. By default, package managers install Redis bound exclusively to the local loopback interface (127.0.0.1). If your web app or API resides in a separate container, virtual machine, or app server, connections directed at the server private IP will be refused.

Inspect active TCP listening sockets on your server:

sudo ss -tlpn | grep 6379
# Expected output when bound only to local loopback:
# LISTEN 0 511 127.0.0.1:6379 0.0.0.0:* users:(("redis-server",pid=1240,fd=6))

To permit connections from your internal private network or Docker bridge, open the Redis configuration file (usually located at /etc/redis/redis.conf):

# Change this default line:
bind 127.0.0.1 ::1

# To your specific private VPC IP and loopback:
bind 127.0.0.1 10.0.1.15

# Or bind to all interfaces on a secure, firewalled internal host:
bind 0.0.0.0

Crucial Security Rule: Protected Mode and Passwords

Never expose Redis port 6379 to the public internet. If you bind to 0.0.0.0, ensure protected-mode yes is configured and set a strong authentication secret using requirepass YOUR_STRONG_SECRET_TOKEN in redis.conf.

Step 3: Resolve Docker and Container Networking Disconnects

In containerized stacks using Docker or Docker Compose, connection refused errors frequently occur because the application container attempts to connect to 127.0.0.1, which resolves to the app container own network namespace rather than the Redis container.

Review the standard solutions for container environments:

  • Use the Docker Service Name: Inside a Docker Compose network, configure your app environment variable as REDIS_HOST=redis (matching the service name in docker-compose.yml), not 127.0.0.1.
  • Expose Host Ports: If connecting from outside the container network, verify that the compose file maps the host port: ports: ["6379:6379"].
  • Check Container Health: Verify the Redis container is healthy with docker ps and check container logs with docker logs redis-container-name.
Environment / Context Typical Root Cause Diagnostic Command Immediate Resolution
Bare-Metal / Linux VM Service terminated, OOM killer, or crashed on restart systemctl status redis-server Restart service, configure vm.overcommit_memory=1
Multi-Server App Architecture Redis bound exclusively to loopback 127.0.0.1 ss -tlpn | grep 6379 Update bind directive in redis.conf to private IP
Docker / Compose Cluster App container targeting loopback instead of DNS name docker network inspect bridge Set REDIS_HOST=redis service hostname in environment
Network / Firewall Boundary UFW, iptables, or Cloud Security Group blocking port 6379 nc -zv SERVER_IP 6379 Allow inbound traffic from app subnet via UFW or security group

Step 4: Authorize Firewall Rules and Validate Network Connectivity

If the service is active and listening on the appropriate IP interface, network packet filtering may be silently dropping or rejecting traffic. Use netcat to test socket reachability directly from your application server:

# Run this command from your client or application host
nc -zv 10.0.1.15 6379

# Success output:
# Connection to 10.0.1.15 6379 port [tcp/*] succeeded!

If the test reports connection refused or times out, adjust your host firewall (UFW) to permit traffic exclusively from your trusted application subnet:

# Allow inbound connections from private VPC subnet (e.g. 10.0.1.0/24)
sudo ufw allow proto tcp from 10.0.1.0/24 to any port 6379

# Reload firewall rules
sudo ufw reload

Step 5: Test Authentication and Redis Ping

Once network connectivity is established, verify operational health with the native Redis command-line interface:

# Direct CLI ping check
redis-cli -h 10.0.1.15 -p 6379 -a YOUR_PASSWORD ping

# Expected return:
# PONG

Need Resilient Cloud Infrastructure and Database Optimization?

From high-throughput Redis clustering and replication to automated disaster recovery, Selestl Solutions provides end-to-end DevOps engineering. Explore our infrastructure consulting services or read more technical engineering breakdowns to harden your stack.

Hardening Your Redis Deployment for Zero-Downtime Operations

Resolving an immediate connection refused incident restores your queue workers, but long-term reliability demands proactive operational hardening:

  1. Implement Client-Side Exponential Backoff: Configure your Redis client libraries with automatic reconnection logic and exponential retry backoff to absorb transient micro-outages gracefully.
  2. Configure Memory Maxlimit Policies: Explicitly set maxmemory 2gb and a sensible eviction policy like maxmemory-policy allkeys-lru to prevent unhandled OOM terminations.
  3. Deploy Redis Sentinel or Managed Clusters: For mission-critical production environments, eliminate single-node failure points by configuring Redis Sentinel for automatic master failover.
  4. Automate Synthetic Monitoring: Establish continuous synthetic TCP and PING health probes that alert your operations team within seconds of daemon failure before customers notice degraded performance.

By pairing methodical socket diagnostics with robust memory governance, you turn unpredictable connection failures into stable, self-healing backend infrastructure.

Frequently Asked Questions

What does Redis Connection Refused Error 111 mean?
Error 111 (ECONNREFUSED) is an operating system socket error indicating that the target server actively rejected the TCP connection request on port 6379, either because the Redis daemon was stopped, bound to the wrong IP interface, or blocked by a firewall.
Why does Redis work locally on 127.0.0.1 but fail from other machines?
By default, Redis binds only to the local loopback interface (127.0.0.1). To accept connections from other servers or containers, you must update the 'bind' directive in redis.conf to include your server private IP or 0.0.0.0.
How do I fix Redis connection refused in Docker Compose?
In Docker Compose, use the service name (e.g., 'redis') as your application REDIS_HOST instead of '127.0.0.1', verify the container is running with 'docker ps', and ensure both containers share the same Docker network.
Why does Redis crash with 'Cannot allocate memory' during background saves?
Redis creates child processes using the fork() system call to write snapshot files (RDB). If Linux kernel memory overcommit is disabled, the fork fails. Enable it by executing 'sudo sysctl vm.overcommit_memory=1'.
Is it safe to set 'bind 0.0.0.0' in Redis?
Setting bind to 0.0.0.0 is only safe if your Redis port 6379 is protected behind a private VPC firewall, protected-mode is enabled, and a strong password is configured via the requirepass directive.
Tags: #Redis #DevOps #Linux #Docker #Database #Backend Architecture #Troubleshooting

Related Articles