Laravel

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:

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:

  1. Sending an Empty String Instead of null on Local Redis: If your local Redis instance has no password configured (requirepass is commented out), setting REDIS_PASSWORD="" in .env sometimes causes Predis to send an explicit AUTH "" command, which Redis rejects. Always use literal null:
    REDIS_PASSWORD=null
  2. 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_USERNAME is set (typically default):
    REDIS_USERNAME=default
    REDIS_PASSWORD="your_managed_redis_password"
  3. Unquoted Special Characters (# or $) in .env: Just like MySQL passwords, an unquoted # in REDIS_PASSWORD is stripped as a comment by Laravel’s .env parser. 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:

  1. Laravel cached the old 127.0.0.1 value inside bootstrap/cache/config.php.
  2. Long-running background daemons (php artisan queue:work or php artisan horizon managed by Supervisor) boot Laravel into memory once when they start. They do not re-read .env on 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.