What causes "Redis connection failed: ${error}." in symfony/symfony?

Confirm reachability: redis-cli -h -p ping.

symfony/symfony · error · Symfony\Component\Cache\Exception\InvalidArgumentException

Redis connection failed: ${error}.

Error message

Redis connection failed: ${error}.

What it means

After invoking Redis::pconnect/connect (or Relay), the code checks isConnected(); if false it inspects the connect error or getLastError(), strips the 'Redis::connect(): ' prefix, and throws InvalidArgumentException describing the connection failure. Typical underlying causes are wrong host/port, refused connection, TLS handshake failure, or AUTH rejected at connect time.

Source

Thrown at src/Symfony/Component/Cache/Traits/RedisTrait.php:333

                try {
                    $extra = [
                        'stream' => self::filterSslOptions($params['ssl'] ?? []) ?: null,
                    ];

                    if (null !== $params['auth']) {
                        $extra['auth'] = $params['auth'];
                    }
                    @$redis->{$connect}($host, $port, (float) $params['timeout'], (string) $params['persistent_id'], $params['retry_interval'], $params['read_timeout'], ...\defined('Redis::SCAN_PREFIX') || !$isRedisExt ? [$extra] : []);

                    set_error_handler(static function ($type, $msg) use (&$error) { $error = $msg; });
                    try {
                        $isConnected = $redis->isConnected();
                    } finally {
                        restore_error_handler();
                    }
                    if (!$isConnected) {
                        $error = preg_match('/^Redis::p?connect\(\): (.*)/', $error ?? $redis->getLastError() ?? '', $error) ? \sprintf(' (%s)', $error[1]) : '';
                        throw new InvalidArgumentException('Redis connection failed: '.$error.'.');
                    }

                    if (0 < $params['tcp_keepalive'] && (!$isRedisExt || \defined('Redis::OPT_TCP_KEEPALIVE'))) {
                        $redis->setOption($isRedisExt ? \Redis::OPT_TCP_KEEPALIVE : Relay::OPT_TCP_KEEPALIVE, $params['tcp_keepalive']);
                    }

                    if (!$redis->select($params['dbindex'])) {
                        $e = preg_replace('/^ERR /', '', $redis->getLastError());
                        throw new InvalidArgumentException('Redis connection failed: '.$e.'.');
                    }
                } catch (\RedisException|\Relay\Exception $e) {
                    throw new InvalidArgumentException('Redis connection failed: '.$e->getMessage());
                }

                return $redis;
            };

            if ($params['lazy']) {

View on GitHub (pinned to 698e28026c)

Solutions

Confirm reachability: redis-cli -h <host> -p <port> ping.
Verify credentials in the DSN and that ACL allows the user.
For TLS, check cert validity and the 'ssl' stream options.
If this happens at boot, add a readiness check / retry-with-backoff before failing the request.

Example fix

# before: REDIS_URL=redis://redis-prod:6379 (service name wrong)
# verify
redis-cli -h redis-prod -p 6379 ping  # (expected PONG)

# after: correct service / port from discovery
REDIS_URL=redis://redis-0.redis:6379

Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight reachability check
$host = parse_url($dsn, PHP_URL_HOST);
$port = parse_url($dsn, PHP_URL_PORT) ?: 6379;
$fp = @fsockopen($host, $port, $e, $es, 2);
if (!is_resource($fp)) { throw new \RuntimeException("redis unreachable: $host:$port"); }
fclose($fp);

Try / catch

use Symfony\Component\Cache\Exception\InvalidArgumentException;
for ($i = 0; $i < 5; ++$i) {
    try { return RedisAdapter::createConnection($dsn, $opts); }
    catch (InvalidArgumentException $e) {
        if (!str_contains($e->getMessage(), 'Redis connection failed')) { throw $e; }
        usleep(500_000 * (2 ** $i));
    }
}
throw new \RuntimeException('Redis unavailable after retries');

Prevention

Use a lazy connection so boot does not fail when Redis is briefly down.
Add retry/backoff for transient network failures.
Monitor Redis availability and surface it in health checks.

When it happens

Trigger: REDIS_URL pointing at a down or wrong-port Redis; firewall/SecurityGroup blocking 6379; TLS cert mismatch on rediss://; AUTH credentials rejected.

Common situations: Redis pod not yet ready at app boot; misconfigured REDIS_URL in prod; rotated password not deployed; mTLS misconfiguration.

Related errors

AI-assisted analysis of symfony/symfony@698e28026c (2026-08-06). Data as JSON: /api/errors/1f258722a163ed6e. Report an issue: GitHub.