phalcon/cphalcon · error · Phalcon\Storage\Exceptions\ConnectionFailed

Cannot connect to the Memcached server(s)

Error message

Cannot connect to the Memcached server(s)

What it means

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.

Source

Thrown at phalcon/Storage/Adapter/Libmemcached.zep:329

        let serializer = strtolower(this->defaultSerializer);

        if (isset(map[serializer])) {
            let this->defaultSerializer = "";
            connection->setOption(\Memcached::OPT_SERIALIZER, map[serializer]);
        }

        this->initSerializer();
    }

    /**
     * @phpstan-param storage_libmemcached_servers $servers
     *
     * @throws ConnectionFailed
     */
    private function setServers(<\Memcached> connection, array servers) -> <static>
    {
        if (true !== connection->addServers(servers)) {
            throw new ConnectionFailed(
                "Cannot connect to the Memcached server(s)"
            );
        }

        return this;
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Format every entry as an array: [['host' => 'cache', 'port' => 11211, 'weight' => 1]] (positional ['cache', 11211] also works)
2. Parse env strings before injecting: split on ':' and cast the port to int
3. Since addServers does not connect, verify the daemon separately: nc -vz cache 11211 or telnet

Example fix

// before
new Libmemcached($factory, ['servers' => ['127.0.0.1:11211']]); // string entries -> ConnectionFailed

// after
new Libmemcached($factory, ['servers' => [['host' => '127.0.0.1', 'port' => 11211, 'weight' => 1]]]);

foreach ($options['servers'] ?? [] as $i => $server) {
    if (!is_array($server) || !isset($server['host'], $server['port'])) {
        throw new InvalidArgumentException("Invalid memcached server entry at {$i}");
    }
    $server['port'] = (int) $server['port'];
}

function isMemcachedServerList(array $servers): bool
{
    return $servers === array_filter($servers, 'is_array');
}

When it happens

Trigger: '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', ''].

Common situations: 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.

Related errors

• Cannot set Memcached client options
• Redis server selected database failed
• The 'storageDir' must be specified in the options
• Configuration file {fileName} cannot be loaded
• The 'dialectClass' '{className}' must implement Phalcon\Db\D

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/52157bbdd3000c95. Report an issue: GitHub.