Redis client / runtime redis connectivity cache
Divya Krishnan Cloud & DevOps Engineer

Redis Error: connect ECONNREFUSED 127.0.0.1:6379

Encountering connect ECONNREFUSED 127.0.0.1:6379 means your client can't reach the Redis server; this guide explains how to fix it.

As a Cloud & DevOps engineer, I've seen ECONNREFUSED errors countless times across various services, and Redis is no exception. This particular error, connect ECONNREFUSED 127.0.0.1:6379, is a clear indication that your application client tried to establish a network connection to a Redis server at 127.0.0.1 on port 6379, but the connection was actively refused by the target machine. This isn't a timeout; it's an explicit "no entry" signal.

What This Error Means

When you see ECONNREFUSED, it means that the operating system on the target machine (in this case, 127.0.0.1) actively rejected the connection attempt from your client. For a connection to be successful, there must be a process listening on the specified IP address and port. In simpler terms, your Redis server isn't available or isn't accepting connections on 127.0.0.1:6379.

This differs from a ETIMEDOUT error, which would indicate that the client couldn't reach the target at all, perhaps due to network congestion or a server being completely offline and unresponsive. ECONNREFUSED tells us that the connection request reached the target, but the target refused it.

Why It Happens

The fundamental reason for this error is that the client's connection request to 127.0.0.1:6379 was met with an active refusal. This usually boils down to one of two primary scenarios:

  1. No Process Listening: There is no Redis server process running and listening for connections on 127.0.0.1:6379. The port is "closed" from the perspective of the server's network stack.
  2. Firewall Blocking: A firewall (either on the client machine, the server machine, or an intermediary network device) is explicitly blocking the connection to 127.0.0.1:6379.

While these are the core reasons, several underlying issues can lead to these scenarios.

Common Causes

Based on my experience troubleshooting this in various environments, here are the most common culprits:

  • Redis Server Not Running: This is by far the most frequent cause. The Redis server daemon might have crashed, failed to start, or simply was never initiated.
  • Incorrect Redis Configuration:
    • Wrong Port: The Redis server is running, but it's listening on a port other than 6379 (e.g., 6380), and your client is still configured for 6379.
    • Wrong Bind Address: The Redis server is configured to bind to a different IP address (e.g., a specific public IP, or 0.0.0.0 for all interfaces) but not 127.0.0.1, while your client is trying to connect to 127.0.0.1. Or, conversely, Redis is bound only to 127.0.0.1 and your client is trying to connect from a remote host.
  • Firewall Rules:
    • Server-Side Firewall: iptables, ufw, firewalld, or similar tools on the server hosting Redis are blocking incoming connections to port 6379.
    • Network Firewall/Security Group: In cloud environments, security groups or network ACLs might be preventing traffic to port 6379.
  • Client Configuration Mismatch: Your application code or configuration file specifies the wrong IP address or port for the Redis instance, even if the Redis server itself is running correctly elsewhere.
  • Resource Exhaustion: Less common for ECONNREFUSED, but if the server is severely overloaded, it might stop accepting new connections, though this often manifests differently.

Step-by-Step Fix

Let's walk through a systematic approach to resolve this error. I've found this process to be highly effective across different setups.

1. Verify Redis Server Status

The first and most critical step is to confirm if your Redis server is actually running.

  • Check on Linux (Systemd):
    bash sudo systemctl status redis-server
    (or redis depending on your distro's package name).
    You should see "active (running)". If it's "inactive (dead)" or "failed", proceed to start it.

  • Check on macOS (Homebrew):
    bash brew services list | grep redis
    It should show redis as started.

  • Directly Check Port (Any OS):
    bash sudo netstat -tulnp | grep 6379
    (On macOS, use lsof -i :6379).
    If Redis is running and listening, you should see an entry like:
    tcp 0 0 127.0.0.1:6379 0.0.0.0:* LISTEN 12345/redis-server
    Note the IP address (127.0.0.1 here) and the process ID (12345). If no output, Redis isn't listening on that port.

  • Check Logs:
    Look for error messages in the Redis logs, typically located at /var/log/redis/redis-server.log or specified in your redis.conf file.
    bash sudo tail -f /var/log/redis/redis-server.log

  • Start Redis Server:
    If Redis is not running:
    bash sudo systemctl start redis-server sudo systemctl enable redis-server # To ensure it starts on boot
    If running manually in development:
    bash redis-server
    Then re-check the status.

2. Verify Redis Configuration

If Redis is running, but you're still getting ECONNREFUSED, the server might not be listening on the expected IP or port.

  • Locate redis.conf:
    The configuration file is usually at /etc/redis/redis.conf or /usr/local/etc/redis.conf (Homebrew). If you started Redis manually, it might be in the current directory or a default location.

  • Check bind directive:
    Open redis.conf and look for the bind directive.
    conf # Default for local development bind 127.0.0.1 # For remote access (use with caution and security measures) # bind 0.0.0.0 # To bind to a specific interface # bind 192.168.1.100
    Ensure that 127.0.0.1 is included if your client is on the same machine and expects to connect to 127.0.0.1. If bind 0.0.0.0 is used, it means Redis will listen on all available network interfaces, including 127.0.0.1.

  • Check port directive:
    Verify the port number. It should default to 6379.
    conf port 6379
    If it's anything else, your client needs to be updated to match.

  • Restart Redis after changes:
    If you modify redis.conf, you must restart the Redis server for changes to take effect.
    bash sudo systemctl restart redis-server

3. Check Network Connectivity and Firewalls

Even if Redis is running and configured correctly, a firewall can block connections.

  • Test Local Connectivity with redis-cli:
    bash redis-cli -h 127.0.0.1 -p 6379 ping
    If this returns PONG, Redis is running and accessible locally. If it returns Could not connect to Redis at 127.0.0.1:6379: Connection refused, it points back to Redis not listening or a local firewall issue.

  • Test with telnet (if available):
    bash telnet 127.0.0.1 6379
    If successful, you'll see a blank screen or a +OK if you type PING and hit enter. If it fails with Connection refused, the problem is still at the server level (Redis not listening or firewall).

  • Check Server-Side Firewalls:

    • UFW (Ubuntu/Debian):
      bash sudo ufw status verbose
      If Redis is enabled: sudo ufw allow 6379/tcp
      Then restart UFW: sudo ufw reload
    • firewalld (CentOS/RHEL):
      bash sudo firewall-cmd --list-all
      If Redis is enabled: sudo firewall-cmd --zone=public --add-port=6379/tcp --permanent
      Then reload firewalld: sudo firewall-cmd --reload
    • iptables (more raw):
      bash sudo iptables -L -n
      Look for rules that might be blocking port 6379. This is generally more complex to manage directly.

    Caution: Temporarily disabling a firewall (e.g., sudo ufw disable) can help diagnose if it's the culprit, but never leave it disabled in a production environment.

4. Verify Client Application Configuration

Finally, double-check your application's configuration. I've often seen this error when the client configuration points to an old or incorrect Redis instance.

  • Ensure your application's connection string, environment variables, or configuration files specify 127.0.0.1 as the host and 6379 as the port.
  • Example: A REDIS_URL environment variable or a config.js file.

Code Examples

Here are common ways clients connect to Redis, showing where the host and port are specified:

Python (using redis-py)

import redis

try:
    # Connect to Redis on localhost, port 6379
    r = redis.StrictRedis(host='127.0.0.1', port=6379, db=0, decode_responses=True)
    r.ping()
    print("Successfully connected to Redis!")
    r.set('mykey', 'Hello from Divya!')
    print(r.get('mykey'))
except redis.exceptions.ConnectionError as e:
    print(f"Redis Connection Error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Node.js (using ioredis)

const Redis = require('ioredis');

const redis = new Redis({
  host: '127.0.0.1',
  port: 6379,
});

redis.on('connect', () => {
  console.log('Successfully connected to Redis!');
  redis.set('mykey', 'Hello from Divya!', (err) => {
    if (err) {
      console.error('Error setting key:', err);
    } else {
      redis.get('mykey', (err, result) => {
        if (err) {
          console.error('Error getting key:', err);
        } else {
          console.log(result);
          redis.quit();
        }
      });
    }
  });
});

redis.on('error', (err) => {
  console.error('Redis Connection Error:', err);
});

Environment-Specific Notes

The troubleshooting steps remain similar, but the context changes significantly across environments.

Local Development

  • Simplicity: Often, you just run redis-server in a terminal, or use brew services start redis on macOS. Firewalls are typically less restrictive.
  • Common Mistakes: Forgetting to start Redis, or having multiple Redis instances running on different ports without realizing it.
  • Fixes: Check process lists (ps aux | grep redis), ensure only one instance is active on the desired port.

Docker

  • Redis in a Container: If Redis is running inside a Docker container, the 127.0.0.1 address refers to the loopback interface within the container.
  • Port Mapping: When running a Redis container, you need to map the container's port to a host port using -p 6379:6379. The first 6379 is the host port your client connects to, and the second is the container's internal Redis port.
    bash docker run --name my-redis -p 6379:6379 -d redis
  • Connecting from another container: If your application is also in a Docker container, you'd typically connect using Docker's internal networking. For instance, if Redis is named my-redis and your app is on the same Docker network, your app would connect to host: my-redis, port 6379 (no host port mapping needed for inter-container communication).
  • Troubleshooting:
    • docker ps: Check if the Redis container is running and port mapping is correct.
    • docker logs my-redis: Check Redis logs inside the container.
    • docker exec -it my-redis redis-cli ping: Test connectivity inside the container.

Cloud Environments (AWS ElastiCache, Azure Cache for Redis, GCP Memorystore)

  • Managed Services: You don't manage the Redis server process directly. The cloud provider ensures it's running.
  • Endpoints: You connect to a specific endpoint (a DNS name) provided by the cloud service, not 127.0.0.1.
  • Security Groups/Network ACLs: This is the most common cause of ECONNREFUSED in cloud environments, in my experience. You must ensure that the security group (AWS), network security group (Azure), or firewall rules (GCP) associated with your Redis instance allows inbound traffic on the Redis port (usually 6379) from your application's IP addresses or security groups.
  • Private Endpoints/VPCs: Often, Redis instances are deployed in a private network (VPC/VNet). Your application must be in the same network or have appropriate peering/VPN connections to reach it.
  • Troubleshooting:
    • Verify the exact endpoint and port from your cloud console.
    • Check security group rules meticulously.
    • Use telnet <endpoint_hostname> 6379 from your application server to test network path.
    • Confirm your application client configuration uses the correct cloud-provided endpoint.

Frequently Asked Questions

Q: Can I connect to Redis remotely?
A: Yes, but it requires careful configuration. You need to change the bind directive in redis.conf from 127.0.0.1 to 0.0.0.0 (to listen on all interfaces) or to a specific network interface's IP address. Additionally, you must configure firewall rules to allow access from your remote IP addresses, and it's highly recommended to enable Redis authentication (requirepass in redis.conf) to prevent unauthorized access.

Q: What if redis-cli ping works but my application still fails?
A: If redis-cli from the application's host works, it indicates the Redis server is reachable and listening. The problem then almost certainly lies with your application's client configuration (e.g., wrong host/port in code, using a different Redis client library that's configured incorrectly, or a local firewall specific to your application's user/process). Double-check the exact connection parameters your application is using.

Q: Is it safe to bind Redis to 0.0.0.0?
A: Binding to 0.0.0.0 makes your Redis instance accessible from any network interface, effectively opening it up to the internet if not protected by a firewall. While sometimes necessary for remote access, it's generally not safe without robust firewall rules that restrict access to known IPs and without enabling Redis authentication.

Q: How do I check Redis logs?
A: The default location for Redis logs on Linux systems is often /var/log/redis/redis-server.log. However, this path can be configured in the redis.conf file using the logfile directive. You can also check journalctl -u redis-server.service on systemd-based systems.

Q: Why does it work after a restart sometimes?
A: If a simple restart fixes the issue, it suggests a transient problem. This could be a race condition during system startup where the client application starts before Redis, or a temporary network glitch. Less commonly, it could indicate a memory leak or resource exhaustion issue within Redis that a restart temporarily alleviates.