{"record":{"id":"1efb3a9a1abd4162","repo":"phalcon/cphalcon","slug":"could-not-connect-to-the-redis-cluster-server-due","errorCode":null,"errorMessage":"Could not connect to the Redis Cluster server due to: {exception message}","messagePattern":"Could not connect to the Redis Cluster server due to: (.+?)","errorType":"exception","errorClass":"Phalcon\\Storage\\Exceptions\\ClusterConnectionFailed","httpStatus":null,"severity":"error","filePath":"phalcon/Storage/Adapter/RedisCluster.zep","lineNumber":135,"sourceCode":"    public function getAdapter() -> var\n    {\n        var connection, ex, options;\n\n        if (null === this->adapter) {\n            let options = this->options;\n\n            try {\n                let connection = new RedisService(\n                    options[\"name\"],\n                    options[\"hosts\"],\n                    options[\"timeout\"],\n                    options[\"readTimeout\"],\n                    options[\"persistent\"],\n                    options[\"auth\"],\n                    options[\"context\"]\n                );\n            } catch Throwable, ex {\n                throw new ClusterConnectionFailed(\n                    \"Could not connect to the Redis Cluster server due to: \" \n                    . ex->getMessage(),\n                    0,\n                    ex\n                );\n            }\n\n            connection->setOption(RedisConsts::OPT_PREFIX, this->prefix);\n\n            this->setSerializer(connection);\n            let this->adapter = connection;\n        }\n\n        return this->adapter;\n    }\n\n    /**\n     * Returns all the keys stored","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Storage/Adapter/RedisCluster.zep#L117-L153","documentation":"Phalcon\\Storage\\Adapter\\RedisCluster::getAdapter() constructs \\RedisCluster from the options (named cluster from redis.ini, or seed 'hosts', plus timeout, readTimeout, persistent, auth, context). Any Throwable from that constructor is wrapped in ClusterConnectionFailed with the underlying message appended and chained via getPrevious().","triggerScenarios":"Seed hosts unreachable or ports wrong; 'hosts' entries not formatted as 'host:port' strings; using 'name' for a cluster not defined in redis.ini (redis.clusters.seeds missing); cluster auth failure; timeout too low for cluster discovery; pointing the RedisCluster adapter at a single non-cluster Redis.","commonSituations":"First cache call after a cluster outage or config change; typos in host strings; forgetting redis.ini seeds for named clusters; local dev against plain Redis while the config says cluster.","solutions":["Verify every seed: redis-cli -h <host> -p <port> PING (cluster nodes must respond to CLUSTER INFO)","Pass hosts as strings: ['hosts' => ['10.0.0.1:7000', '10.0.0.2:7001']]","For named clusters set redis.clusters.seeds / redis.clusters.auth in redis.ini and use options ['name' => 'mycluster']","Inspect getPrevious() for the real phpredis error and raise timeout/readTimeout if discovery is slow"],"exampleFix":"// before\nnew RedisCluster($factory, ['hosts' => ['10.0.0.1']]); // missing port -> constructor throws\n\n// after\nnew RedisCluster($factory, ['hosts' => ['10.0.0.1:7000', '10.0.0.2:7001']]);","handlingStrategy":"try-catch","validationCode":"// fail fast at boot instead of the first cache hit\nforeach ($options['hosts'] as $host) {\n    [$h, $p] = array_pad(explode(':', $host, 2), 2, '6379');\n    $sock = @fsockopen($h, (int) $p, $errno, $errstr, 0.5);\n    if ($sock === false) {\n        throw new RuntimeException(\"Cluster seed {$host} unreachable: {$errstr}\");\n    }\n    fclose($sock);\n}","typeGuard":null,"tryCatchPattern":"try {\n    $cluster->getAdapter();\n} catch (\\Phalcon\\Storage\\Exceptions\\ClusterConnectionFailed $e) {\n    // the underlying phpredis error is in getMessage() and getPrevious()\n    $logger->error('RedisCluster connect failed: ' . $e->getMessage(), ['previous' => $e->getPrevious()]);\n    throw $e;\n}","preventionTips":["Format hosts strictly as 'host:port' strings; validate in config tests","For named clusters keep redis.ini seeds in the same deploy unit as the app","Warm the cluster connection at boot so outages surface in health checks, not user requests"],"tags":["php","phalcon","redis","cluster","cache","network","connection"],"backgroundTag":"connection-refused","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}