laravel/framework · error · BroadcastException

Redis error: %s.

Error message

Redis error: %s.

What it means

RedisBroadcaster::broadcast() catches Predis ConnectionException or a phpredis RedisException raised while publishing to the Redis pub/sub channel and re-throws as BroadcastException with the underlying message. It signals the Redis connection backing the broadcaster is unreachable or erroring.

Source

Thrown at src/Illuminate/Broadcasting/Broadcasters/RedisBroadcaster.php:157

                    $connection->client()->getClientBy('slot', mt_rand(0, 16383))
                );

                if ($events = $connection->getEventDispatcher()) {
                    $randomClusterNodeConnection->setEventDispatcher($events);
                }

                $randomClusterNodeConnection->eval(
                    $this->broadcastMultipleChannelsScript(),
                    0, $payload, ...$this->formatChannels($channels)
                );
            } else {
                $connection->eval(
                    $this->broadcastMultipleChannelsScript(),
                    0, $payload, ...$this->formatChannels($channels)
                );
            }
        } catch (ConnectionException|RedisException $e) {
            throw new BroadcastException(
                sprintf('Redis error: %s.', $e->getMessage())
            );
        }
    }

    /**
     * Get the Lua script for broadcasting to multiple channels.
     *
     * ARGV[1] - The payload
     * ARGV[2...] - The channels
     *
     * @return string
     */
    protected function broadcastMultipleChannelsScript()
    {
        return <<<'LUA'
for i = 2, #ARGV do
  redis.call('publish', ARGV[i], ARGV[1])

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Check the Redis connection defined under 'redis' in config/database.php and ensure REDIS_HOST/PORT/PASSWORD are correct.
2. Verify redis-cli can connect with the same credentials from the app host.
3. Ensure config/broadcasting.php 'connections.redis.connection' points to a defined Redis connection.
4. Restart the Redis server / reconnect the tunnel, then retry the broadcast.

Example fix

// before
'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
],
// .env has a wrong REDIS_PORT

// after
// .env
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
// verify with: redis-cli -h 127.0.0.1 -p 6379 ping

// Health-check the Redis connection before broadcasting
$redis = app('redis')->connection(config('broadcasting.connections.redis.connection'));
try {
    $redis->ping();
} catch (\RedisException|\Predis\Connection\ConnectionException $e) {
    throw new \RuntimeException('Redis unreachable, cannot broadcast: '.$e->getMessage());
}

// n/a - infrastructure error

try {
    broadcast(new OrderShipped($order));
} catch (\Illuminate\Broadcasting\BroadcastException $e) {
    if (str_starts_with($e->getMessage(), 'Redis error')) {
        // schedule retry, alert ops
    }
    throw $e;
}

When it happens

Trigger: Calling broadcast() when the Redis server is down, unreachable, refuses auth, or when the configured broadcast connection name maps to a non-existent Redis connection. Also triggered by a Lua eval failure on cluster nodes.

Common situations: REDIS_HOST/REDIS_PORT/REDIS_PASSWORD wrong in .env. Redis service not started in dev. Docker/SSH tunnel to Redis dropped. Using a Redis cluster without all nodes reachable. The 'broadcasting' => 'redis' connection in config/broadcasting.php references a missing redis connection.

Related errors

• Failed to create broadcaster for connection "{$name}" with e
• Broadcast connection [{$name}] is not defined.
• Driver [{$config['driver']}] is not supported.
• Ably error: %s
• Class based channel must define a "join" method.

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/ea3ae5a84264d771.json. Report an issue: GitHub.