Connection refused errors occur when your application cannot establish a TCP connection to the Redis server. This typically means Redis isn't running, is listening on a different port, or network/firewall rules are blocking the connection.
The "Connection refused" error happens when your client attempts to connect to Redis on a specific host and port, but the operating system actively rejects the connection. This indicates that either: 1. The Redis server process is not running 2. Redis is not listening on the host/port your client expects 3. Network or firewall rules are blocking the connection 4. The Redis service has crashed or been terminated The error message typically includes the host and port, like "connect ECONNREFUSED 127.0.0.1:6379", making it clear exactly where the client was trying to connect.
Use the redis-cli ping command to verify the Redis server is responding:
redis-cli pingIf Redis is running, you'll see "PONG" response. If you get a connection refused error, Redis is not running.
On Linux systems, you can also check the process:
ps aux | grep redis-serverUse the appropriate command for your system:
Linux (systemd):
sudo systemctl start redis-serverLinux (service command):
sudo service redis-server startmacOS (Homebrew):
brew services start redisManual start:
redis-serverAfter starting, verify it's running with:
redis-cli pingCheck what host and port your application is trying to connect to. Look for Redis connection settings in your code or configuration files:
- Default host: 127.0.0.1 or localhost
- Default port: 6379
Make sure your application connects to the correct values. For Docker environments, use the Redis service name as the host (not localhost).
Test connectivity to the expected host/port using telnet:
telnet localhost 6379If connection succeeds, you'll see a prompt. If refused, Redis is not listening on that address.
If connecting from a different machine, verify firewall allows port 6379.
On UFW (Ubuntu/Debian):
sudo ufw allow 6379Check current status:
sudo ufw statusOn iptables:
sudo iptables -L | grep 6379If the port is blocked, open it with:
sudo iptables -A INPUT -p tcp --dport 6379 -j ACCEPTRedis configuration controls which addresses it listens on. If Redis only binds to localhost (127.0.0.1) but your client is on a different network, you'll get connection refused.
Check the Redis configuration file (typically /etc/redis/redis.conf):
grep '^bind' /etc/redis/redis.conf- If it shows bind 127.0.0.1, Redis only accepts local connections
- For Docker or remote access, it should be bind 0.0.0.0
Edit the config file and change the bind address, then restart Redis:
sudo systemctl restart redis-serverVerify another process isn't already using port 6379:
On Linux/macOS:
lsof -i :6379On Linux with netstat:
netstat -an | grep 6379If another process occupies the port, either:
1. Stop that process
2. Configure Redis to use a different port
3. Configure your application to connect to the other process's port if that's what you intended
Docker Considerations: When running Redis in Docker and connecting from another container, use the Redis service name as the host (e.g., "redis" instead of "localhost"). Make sure containers are on the same network. If Redis is outside Docker, use the host's IP address (not localhost).
Protected Mode: Redis 6.0+ enables protected-mode by default, which requires either localhost connection or a password. If you're getting refused connections from remote machines even with the bind address set correctly, disable protected-mode in redis.conf or set a requirepass.
DNS Resolution: In some environments (Kubernetes, complex Docker setups), DNS resolution delays can cause timeouts that appear as connection refused. Ensure your client uses the correct hostname and allow sufficient connection timeout.
Cloud Deployments: On Railway, AWS ElastiCache, or other cloud Redis services, the host/port differ from local defaults. Always use the connection string provided by your cloud provider. Cloud firewalls may also require inbound rules.
ERR fsync error
How to fix "ERR fsync error" in Redis
CLUSTERDOWN The cluster is down
How to fix 'CLUSTERDOWN The cluster is down' in Redis
ERR Job for redis-server.service failed because a timeout was exceeded
Job for redis-server.service failed because a timeout was exceeded
ERR Unbalanced XREAD list of streams
How to fix "ERR Unbalanced XREAD list" in Redis
ERR syntax error
How to fix "ERR syntax error" in Redis