Fixing 'Connection refused [tcp://127.0.0.1:6379]' (RedisException & Predis) in Laravel & Docker
When you switch your CACHE_STORE, SESSION_DRIVER, or QUEUE_CONNECTION to redis in Laravel, or boot up a queue worker, your application immediately crashes with one of two connection errors depending on your configured Redis client.
If you are using predis/predis:
Predis\Connection\ConnectionException
Connection refused [tcp://127.0.0.1:6379]
If you are using the native phpredis C extension (the default in Laravel 10, 11, and 12):
RedisException
Connection refused
Or, if the PHP extension itself is missing from your runtime:
Error
Class "Redis" not found
Port 6379 is the default TCP port for Redis. A Connection refused error means your Laravel container or server reached the target IP address, but no active Redis daemon was listening on that network interface—or the daemon rejected the socket handshake.
Quick Diagnostic Reference
Match your environment and error message to jump directly to the working fix:
| Environment / Error Signature | Root Cause | Jump to Fix |
|---|---|---|
| Running inside Docker Compose or Laravel Sail | REDIS_HOST=127.0.0.1 points to the PHP container instead of the redis container |
Fix 1 |
| Ubuntu / Debian VPS or Local Linux / macOS | redis-server daemon is stopped, not installed, or bound to IPv6 only |
Fix 2 |
Error: Class "Redis" not found |
Laravel defaults to phpredis, but the ext-redis PHP extension is not installed |
Fix 3 |
WRONGPASS or NOAUTH Authentication required |
Unquoted # in REDIS_PASSWORD or Redis 6+ ACL username mismatch |
Fix 4 |
Fixed .env, but Queue Workers still throw 6379 error |
Long-running queue:work / Horizon processes hold stale config in memory |
Fix 5 |
1. Docker Compose & Laravel Sail (REDIS_HOST=127.0.0.1 vs redis)
Inside a Dockerized Laravel setup, every service defined in docker-compose.yml runs inside its own isolated network namespace.
When your .env file has REDIS_HOST=127.0.0.1, your PHP-FPM container looks for a Redis server running inside the PHP container itself rather than reaching across the Docker bridge network to your Redis container.
Step 1: Point REDIS_HOST to the Docker Service Name
Open your docker-compose.yml file and check the exact service name of your Redis container (typically redis):
services:
laravel.test:
# ...
redis:
image: 'redis:alpine'
ports:
- '${FORWARD_REDIS_PORT:-6379}:6379'
Update your .env file so REDIS_HOST matches that service name:
# ❌ BROKEN inside Docker containers:
REDIS_HOST=127.0.0.1
# ✅ WORKING inside Docker Compose & Laravel Sail:
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379
(Note: This is the exact same container loopback trap that happens with MySQL on port 3306. If your database migrations also fail with connection refused inside Docker, see our guide on Fixing SQLSTATE[HY000] [2002] Connection Refused in Laravel).
Step 2: Running Artisan Commands from the Host Machine
If you set REDIS_HOST=redis and run php artisan directly from your Windows or macOS terminal outside of Docker, your host OS won’t know how to resolve the hostname redis. Always execute Artisan commands inside the container:
# Using Laravel Sail:
./vendor/bin/sail artisan cache:clear
# Using standard Docker Compose:
docker compose exec app php artisan cache:clear
2. Ubuntu / Debian VPS & Local Machine (redis-server Not Running)
If you are running Laravel directly on an Ubuntu/Debian VPS, macOS, or Windows WSL2 without Docker, Connection refused [tcp://127.0.0.1:6379] means the redis-server system service is either stopped or not installed.
Step 1: Verify the Redis Daemon Status
Check if Redis is actively listening on port 6379:
sudo systemctl status redis-server
If the service is not installed on Ubuntu/Debian, install and enable it:
sudo apt update
sudo apt install redis-server -y
sudo systemctl enable --now redis-server
(On macOS with Homebrew, run brew install redis followed by brew services start redis).
Step 2: Check /etc/redis/redis.conf Bind Directives
If redis-server is running but 127.0.0.1:6379 still refuses connections, open /etc/redis/redis.conf and verify the bind line:
sudo nano /etc/redis/redis.conf
Ensure Redis is bound to IPv4 loopback (127.0.0.1) and that supervised is set appropriately for systemd:
bind 127.0.0.1 -::1
port 6379
supervised systemd
Restart the service and verify the socket is listening using ss:
sudo systemctl restart redis-server
sudo ss -tulpn | grep 6379
Expected output:
tcp LISTEN 0 511 127.0.0.1:6379 0.0.0.0:* users:(("redis-server",pid=1492,fd=6))
3. Fixing Class "Redis" not found (phpredis vs predis)
Modern Laravel versions set REDIS_CLIENT=phpredis by default inside config/database.php. Unlike Composer packages, phpredis is a compiled C extension that must be installed at the operating system / PHP-FPM level.
You have two ways to resolve this:
Option A: Install the Native php-redis Extension (Recommended for Production)
The C extension is significantly faster under high queue and cache throughput. Install it for your active PHP version:
# Ubuntu / Debian (replace 8.3 with your active PHP version):
sudo apt install php8.3-redis -y
sudo systemctl restart php8.3-fpm
# Inside a Debian/Ubuntu Dockerfile:
RUN pecl install redis && docker-php-ext-enable redis
(Security Note: Whenever you update or install PHP extensions on a production server, verify your core PHP runtime is patched against recent SAPI vulnerabilities. See our remediation guide on How to Patch PHP2Shell CVE-2026-109618 & CVE-2026-109619).
Option B: Switch to the Pure-PHP predis/predis Package
If you are on a restricted host where you cannot install PHP C extensions, install predis/predis via Composer and switch REDIS_CLIENT in your .env:
composer require predis/predis
Then update your .env file:
REDIS_CLIENT=predis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
4. Redis 6+ & 7+ Authentication Traps (NOAUTH / WRONGPASS)
If your TCP connection succeeds on port 6379 but immediately fails with NOAUTH Authentication required or WRONGPASS invalid username-password pair, check these three configuration pitfalls:
- Sending an Empty String Instead of
nullon Local Redis: If your local Redis instance has no password configured (requirepassis commented out), settingREDIS_PASSWORD=""in.envsometimes causes Predis to send an explicitAUTH ""command, which Redis rejects. Always use literalnull:REDIS_PASSWORD=null - Managed Redis Providers Requiring ACL Usernames (Redis 6+ / 7+):
Cloud providers (AWS ElastiCache, Upstash, DigitalOcean Managed Redis, Laravel Cloud) use Redis Access Control Lists (ACLs). Ensure
REDIS_USERNAMEis set (typicallydefault):REDIS_USERNAME=default REDIS_PASSWORD="your_managed_redis_password" - Unquoted Special Characters (
#or$) in.env: Just like MySQL passwords, an unquoted#inREDIS_PASSWORDis stripped as a comment by Laravel’s.envparser. Always wrap passwords in double quotes. For a breakdown of how dotenv parses special characters, see Fixing SQLSTATE[HY000] [1045] Access Denied in Laravel.
5. Clearing Cached Configs & Restarting Stuck Queue Workers
A common trap in production is fixing REDIS_HOST in .env, verifying that web requests work, and yet still seeing Connection refused [tcp://127.0.0.1:6379] flooding storage/logs/laravel.log every few seconds.
Why this happens:
- Laravel cached the old
127.0.0.1value insidebootstrap/cache/config.php. - Long-running background daemons (
php artisan queue:workorphp artisan horizonmanaged by Supervisor) boot Laravel into memory once when they start. They do not re-read.envon subsequent jobs until the worker process restarts.
Run these three commands in sequence to flush the cache and gracefully restart all background workers:
# 1. Clear the compiled configuration file
php artisan config:clear
# 2. Signal all Supervisor queue workers to finish their current job and reboot
php artisan queue:restart
# 3. If using Laravel Horizon, terminate the master supervisor so systemd/Supervisor restarts it:
php artisan horizon:terminate
(Note: If php artisan config:clear or your queue workers throw file write errors when writing to storage/logs/laravel.log, your Supervisor worker is likely running under a mismatched Linux user. Check our guide on Fixing storage/logs/laravel.log Permission Denied in Linux & Docker to align www-data permissions).
Verification: Test the Redis Handshake
First, test the raw Redis server response from your terminal using redis-cli:
redis-cli -h 127.0.0.1 -p 6379 ping
# Expected output: PONG
Next, verify that Laravel can write and read a test key through its Redis facade using Artisan Tinker:
php artisan tinker
Run this snippet inside the Tinker prompt:
use Illuminate\Support\Facades\Redis;
Redis::set('health_check', 'connected');
Redis::get('health_check');
// Expected output: "connected"
If Tinker returns "connected", your Redis connection is active across cache, sessions, and queues. If your Redis connection uses TLS (rediss://) on a managed cloud provider and fails with a certificate verification error, consult our guide on Fixing cURL error 60: SSL certificate problem in Laravel & Docker.