{"record":{"id":"1f258722a163ed6e","repo":"symfony/symfony","slug":"redis-connection-failed-error","errorCode":null,"errorMessage":"Redis connection failed: ${error}.","messagePattern":"Redis connection failed: (.+?)\\.","errorType":"exception","errorClass":"Symfony\\Component\\Cache\\Exception\\InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Symfony/Component/Cache/Traits/RedisTrait.php","lineNumber":333,"sourceCode":"                try {\n                    $extra = [\n                        'stream' => self::filterSslOptions($params['ssl'] ?? []) ?: null,\n                    ];\n\n                    if (null !== $params['auth']) {\n                        $extra['auth'] = $params['auth'];\n                    }\n                    @$redis->{$connect}($host, $port, (float) $params['timeout'], (string) $params['persistent_id'], $params['retry_interval'], $params['read_timeout'], ...\\defined('Redis::SCAN_PREFIX') || !$isRedisExt ? [$extra] : []);\n\n                    set_error_handler(static function ($type, $msg) use (&$error) { $error = $msg; });\n                    try {\n                        $isConnected = $redis->isConnected();\n                    } finally {\n                        restore_error_handler();\n                    }\n                    if (!$isConnected) {\n                        $error = preg_match('/^Redis::p?connect\\(\\): (.*)/', $error ?? $redis->getLastError() ?? '', $error) ? \\sprintf(' (%s)', $error[1]) : '';\n                        throw new InvalidArgumentException('Redis connection failed: '.$error.'.');\n                    }\n\n                    if (0 < $params['tcp_keepalive'] && (!$isRedisExt || \\defined('Redis::OPT_TCP_KEEPALIVE'))) {\n                        $redis->setOption($isRedisExt ? \\Redis::OPT_TCP_KEEPALIVE : Relay::OPT_TCP_KEEPALIVE, $params['tcp_keepalive']);\n                    }\n\n                    if (!$redis->select($params['dbindex'])) {\n                        $e = preg_replace('/^ERR /', '', $redis->getLastError());\n                        throw new InvalidArgumentException('Redis connection failed: '.$e.'.');\n                    }\n                } catch (\\RedisException|\\Relay\\Exception $e) {\n                    throw new InvalidArgumentException('Redis connection failed: '.$e->getMessage());\n                }\n\n                return $redis;\n            };\n\n            if ($params['lazy']) {","sourceCodeStart":315,"sourceCodeEnd":351,"githubUrl":"https://github.com/symfony/symfony/blob/698e28026c22cf35d032cdb6e800db48b1535790/src/Symfony/Component/Cache/Traits/RedisTrait.php#L315-L351","documentation":"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.","triggerScenarios":"REDIS_URL pointing at a down or wrong-port Redis; firewall/SecurityGroup blocking 6379; TLS cert mismatch on rediss://; AUTH credentials rejected.","commonSituations":"Redis pod not yet ready at app boot; misconfigured REDIS_URL in prod; rotated password not deployed; mTLS misconfiguration.","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."],"exampleFix":"# before: REDIS_URL=redis://redis-prod:6379 (service name wrong)\n# verify\nredis-cli -h redis-prod -p 6379 ping  # (expected PONG)\n\n# after: correct service / port from discovery\nREDIS_URL=redis://redis-0.redis:6379","handlingStrategy":"retry","validationCode":"// Pre-flight reachability check\n$host = parse_url($dsn, PHP_URL_HOST);\n$port = parse_url($dsn, PHP_URL_PORT) ?: 6379;\n$fp = @fsockopen($host, $port, $e, $es, 2);\nif (!is_resource($fp)) { throw new \\RuntimeException(\"redis unreachable: $host:$port\"); }\nfclose($fp);","typeGuard":null,"tryCatchPattern":"use Symfony\\Component\\Cache\\Exception\\InvalidArgumentException;\nfor ($i = 0; $i < 5; ++$i) {\n    try { return RedisAdapter::createConnection($dsn, $opts); }\n    catch (InvalidArgumentException $e) {\n        if (!str_contains($e->getMessage(), 'Redis connection failed')) { throw $e; }\n        usleep(500_000 * (2 ** $i));\n    }\n}\nthrow new \\RuntimeException('Redis unavailable after retries');","preventionTips":["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."],"tags":["redis","network","connection"],"analyzedSha":"698e28026c22cf35d032cdb6e800db48b1535790","analyzedAt":"2026-08-06T23:40:49.025Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}