AWS Redis Connection Refused: Troubleshooting ECONNREFUSED and tcp 127.0.0.1:6379

Understanding the Error

The Connection refused error (often appearing as ECONNREFUSED, Connection refused tcp 127.0.0.1:6379, php_network_getaddresses: getaddrinfo failed, or Predis\Connection\ConnectionException) is a fundamental networking error. It occurs when your application (the client) attempts to establish a TCP connection to a Redis server, but the operating system at the target IP and port actively rejects the connection.

This rejection means one of two things: either there is no service listening on that specific IP and port combination, or a firewall is explicitly configured to send a TCP RST (reset) packet back to the client. This is different from a connection timeout, where packets are simply dropped and the client waits indefinitely.

When running infrastructure on AWS, this error manifests across several different architectures, each requiring a distinct troubleshooting approach.

Scenario 1: Self-hosted Redis on Amazon EC2

If you have provisioned an EC2 instance and installed Redis manually (e.g., using apt install redis-server on Ubuntu), the default configuration is highly restrictive for security reasons.

By default, the redis.conf file contains the directive bind 127.0.0.1 -::1. This tells the Redis daemon to only listen for connections originating from the loopback interface (the EC2 instance itself). If a web server on a different EC2 instance tries to connect to the Redis EC2 instance's private IP, the operating system will refuse the connection because Redis is not listening on the network interface associated with that private IP.

Scenario 2: Amazon ElastiCache for Redis

When using managed Amazon ElastiCache, the infrastructure is abstracted, but network security rules are strictly enforced. A Connection refused or timeout when connecting to an ElastiCache primary endpoint is almost always related to AWS Security Groups or Amazon VPC networking.

ElastiCache clusters are deployed within a specific VPC. If your client application (an ECS container, an EC2 instance, or an AWS Lambda function) is in a different VPC without peering, or if the Security Group attached to the ElastiCache cluster does not explicitly allow inbound TCP traffic on port 6379 from the client's Security Group, the connection will fail.

Scenario 3: Containerized Environments (Docker, Kubernetes, Laravel Sail)

A very common source of Connection refused tcp 127.0.0.1:6379 occurs in local development environments or Kubernetes clusters. Developers often leave their application's .env configuration pointing to REDIS_HOST=127.0.0.1.

In a Dockerized environment (like Laradock for Laravel), 127.0.0.1 refers to the localhost inside the specific container where the application is running, not the host machine or the Redis container. Since Redis is running in a separate, isolated container, there is no Redis service listening on 127.0.0.1 within the application container, resulting in an immediate connection refusal.

Step 1: Diagnose the Redis Service State

Before modifying network configurations, you must verify that the Redis service is actually running and healthy.

If you have SSH access to the server hosting Redis, log in and check the process status:

sudo systemctl status redis-server
# or
sudo systemctl status redis

If the output shows Active: inactive (dead) or failed, the service is not running. Check the logs to determine why it crashed:

sudo journalctl -u redis-server --no-pager | tail -n 50

Common reasons for startup failure include insufficient memory, permission issues on the /var/lib/redis directory, or syntax errors in the redis.conf file.

If the service is running, test local connectivity using the Redis CLI:

redis-cli ping

If this returns PONG, Redis is functioning correctly on localhost. If redis-cli ping returns Connection refused, Redis is either listening on a non-standard port, using a Unix domain socket instead of TCP, or the service is completely locked up.

Next, verify exactly which network interfaces and ports Redis is bound to:

sudo ss -tulpn | grep redis
# or
sudo netstat -plnt | grep 6379

Look at the Local Address:Port column.

• If it says 127.0.0.1:6379, Redis is only accessible locally.
• If it says 0.0.0.0:6379 or *:6379, Redis is listening on all IPv4 interfaces.
• If it says 10.x.x.x:6379, it is bound to a specific private IP.

Step 2: Fix Redis Configuration (Bind Address)

If your architecture requires remote connections (e.g., separating your web tier from your caching tier) and Redis is bound only to 127.0.0.1, you must update the configuration.

1. Open the Redis configuration file using a text editor:

sudo nano /etc/redis/redis.conf

2. Locate the network binding directive. Search for the line starting with bind.

3. Modify the binding. To allow connections from any IP address (which relies entirely on AWS Security Groups for protection):

# Change this:
# bind 127.0.0.1 -::1

# To this:
bind 0.0.0.0

Alternatively, for better defense-in-depth, bind it specifically to localhost and the server's private network IP:

bind 127.0.0.1 10.0.1.55

4. Review protected-mode. By default, Redis enables protected mode. If you bind to external interfaces but do not configure a password (requirepass), Redis will still reject external commands to prevent accidental exposure to the internet. If you are operating entirely within a secure AWS VPC with strict Security Groups, you can disable it:

protected-mode no

(Note: It is highly recommended to leave protected mode on and configure a strong password instead).

5. Restart the Redis service to apply the changes:

sudo systemctl restart redis-server

Step 3: Resolve AWS Security Group Misconfigurations

If Redis is bound to 0.0.0.0 or the correct private IP, but remote EC2 instances or containers still receive Connection refused or timeouts, the issue lies within AWS network security.

Follow these steps in the AWS Management Console:

1. Locate the Target Security Group: Find the Security Group attached to your Redis EC2 instance or your Amazon ElastiCache cluster.
2. Edit Inbound Rules: Select the Security Group and go to the "Inbound rules" tab. Click "Edit inbound rules".
3. Add a Custom Rule:
   • Type: Custom TCP
   • Port range: 6379 (or your custom Redis port)
   • Source: Do not use 0.0.0.0/0 (Anywhere-IPv4) unless you want your database exposed to ransomware bots. Instead, specify the Security Group ID of your client applications (e.g., sg-0abcd1234efgh5678). This ensures that only resources assigned to that specific client Security Group can access the Redis port.
4. Save Rules: Apply the changes. Security Group updates take effect almost immediately.

If you are operating across VPCs, ensure that VPC Peering or a Transit Gateway is configured correctly, and that the subnet route tables have routes directing traffic to the peered CIDR blocks.

Step 4: Resolving Application and Framework-Specific Issues

Different frameworks and environments produce specific variations of this error.

Laravel (Predis\Connection\ConnectionException)

In Laravel, connecting to Redis is handled by the predis/predis or phpredis extensions. If you see the error Connection refused tcp 127.0.0.1:6379, your application is looking in the wrong place.

1. Open your .env file.
2. Locate the Redis configuration block.
3. If you are running Laravel natively via php artisan serve and Redis locally, REDIS_HOST=127.0.0.1 is correct. However, if you are using Laravel Sail or Laradock, the web container and Redis container are separate.
4. Change the host to match the Docker Compose service name for Redis. For example:

REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

5. Clear your configuration cache, as Laravel heavily caches the .env file:

php artisan config:clear

Kubernetes (econnrefused)

In Kubernetes, pods should communicate via Services. If a Node.js or Python application pod reports econnrefused, check your Deployment manifests.

The environment variable defining the Redis host should not be localhost. It must be the DNS name of the Kubernetes Service exposing Redis.

For example, if you deployed Redis via a Helm chart and the service is named redis-master in the default namespace, your connection string should point to:

redis-master.default.svc.cluster.local

Verify that the service actually has endpoints attached to it (meaning the Redis pods are running and passing readiness probes):

kubectl get endpoints redis-master

If the endpoints list is empty, your Redis pods are crashing or failing health checks, preventing the Service from routing traffic to them.

Windows Subsystem for Linux (WSL)

When running a Redis server inside WSL2 and trying to connect from a Windows application (like a GUI database client), you might encounter Connection refused.

WSL2 utilizes a lightweight utility VM, meaning it operates on a separate virtual network adapter with its own IP address. While Windows attempts to forward localhost ports to WSL2, it can sometimes be unreliable.

To fix this:

1. Open your WSL2 terminal.
2. Edit /etc/redis/redis.conf and change bind 127.0.0.1 to bind 0.0.0.0.
3. Restart Redis inside WSL2.
4. Find the actual IP address of the WSL2 instance by running ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'.
5. Connect your Windows client directly to that specific IP address rather than 127.0.0.1.