{"record":{"id":"52157bbdd3000c95","repo":"phalcon/cphalcon","slug":"cannot-connect-to-the-memcached-server-s","errorCode":null,"errorMessage":"Cannot connect to the Memcached server(s)","messagePattern":"Cannot connect to the Memcached server\\(s\\)","errorType":"exception","errorClass":"Phalcon\\Storage\\Exceptions\\ConnectionFailed","httpStatus":null,"severity":"error","filePath":"phalcon/Storage/Adapter/Libmemcached.zep","lineNumber":329,"sourceCode":"        let serializer = strtolower(this->defaultSerializer);\n\n        if (isset(map[serializer])) {\n            let this->defaultSerializer = \"\";\n            connection->setOption(\\Memcached::OPT_SERIALIZER, map[serializer]);\n        }\n\n        this->initSerializer();\n    }\n\n    /**\n     * @phpstan-param storage_libmemcached_servers $servers\n     *\n     * @throws ConnectionFailed\n     */\n    private function setServers(<\\Memcached> connection, array servers) -> <static>\n    {\n        if (true !== connection->addServers(servers)) {\n            throw new ConnectionFailed(\n                \"Cannot connect to the Memcached server(s)\"\n            );\n        }\n\n        return this;\n    }\n}\n","sourceCodeStart":311,"sourceCodeEnd":337,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Storage/Adapter/Libmemcached.zep#L311-L337","documentation":"On first use, Libmemcached passes options['servers'] (Phalcon default: [['host' => '127.0.0.1', 'port' => 11211, 'weight' => 1]]) straight to Memcached::addServers(); when the extension cannot register the list (malformed entries) it returns false and Phalcon throws ConnectionFailed('Cannot connect to the Memcached server(s)'). Note addServers() does not actually open connections — a false return is a config-shape problem, not a network one.","triggerScenarios":"'servers' entries formatted as 'host:port' strings instead of arrays; entries missing the port; a non-array 'servers' value; an empty/invalid element inside the list, e.g. ['127.0.0.1:11211', ''].","commonSituations":"Porting config from redis/predis-style 'host:port' strings; MEMCACHED_SERVERS=cache:11211 env vars pasted verbatim; forgetting Phalcon already defaults to localhost so an overriden list must repeat the full array shape.","solutions":["Format every entry as an array: [['host' => 'cache', 'port' => 11211, 'weight' => 1]] (positional ['cache', 11211] also works)","Parse env strings before injecting: split on ':' and cast the port to int","Since addServers does not connect, verify the daemon separately: nc -vz cache 11211 or telnet"],"exampleFix":"// before\nnew Libmemcached($factory, ['servers' => ['127.0.0.1:11211']]); // string entries -> ConnectionFailed\n\n// after\nnew Libmemcached($factory, ['servers' => [['host' => '127.0.0.1', 'port' => 11211, 'weight' => 1]]]);","handlingStrategy":"validation","validationCode":"foreach ($options['servers'] ?? [] as $i => $server) {\n    if (!is_array($server) || !isset($server['host'], $server['port'])) {\n        throw new InvalidArgumentException(\"Invalid memcached server entry at {$i}\");\n    }\n    $server['port'] = (int) $server['port'];\n}","typeGuard":"function isMemcachedServerList(array $servers): bool\n{\n    return $servers === array_filter($servers, 'is_array');\n}","tryCatchPattern":null,"preventionTips":["Normalize env-provided 'host:port' strings into [host, port] arrays at config load time","Remember Phalcon already defaults to localhost:11211; only override with full array entries","Since addServers does not connect, probe the daemon with nc/redis-cli-style checks in CI, not via this exception"],"tags":["php","phalcon","memcached","cache","configuration"],"backgroundTag":"invalid-server-config","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}