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

Cannot set Memcached client options

Error message

Cannot set Memcached client options

What it means

On first use (Libmemcached::getAdapter() during the first cache operation), Phalcon merges your 'client' options over built-in failover defaults (OPT_CONNECT_TIMEOUT, DISTRIBUTION_CONSISTENT, OPT_SERVER_FAILURE_LIMIT, OPT_REMOVE_FAILED_SERVERS, OPT_RETRY_TIMEOUT) and calls Memcached::setOptions(). If ext-memcached rejects any single option, setOptions() returns false and Phalcon throws InvalidConfiguration('Cannot set Memcached client options').

Source

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

        return this->getAdapter()
                   ->set(
                       key,
                       this->getSerializedData(value),
                       this->getTtl(ttl)
                   )
        ;
    }

    /**
     * @phpstan-param storage_libmemcached_client $client
     *
     * @throws InvalidConfiguration
     */
    private function setOptions(<\Memcached> connection, array client) -> <static>
    {
        if (true !== connection->setOptions(client)) {
            throw new InvalidConfiguration(
                "Cannot set Memcached client options"
            );
        }

        return this;
    }

    private function setSasl(
        <\Memcached> connection,
        string saslUser,
        string saslPass
    ) -> <static> {
        if (true !== empty(saslUser)) {
            connection->setSaslAuthData(saslUser, saslPass);
        }

        return this;
    }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use \Memcached::OPT_* constant keys and verify each value's type against the extension docs
2. Bisect the offending option with a throwaway instance: foreach ($client as $k => $v) { var_dump($k, (new \Memcached())->setOption($k, $v)); }
3. Remove options your ext-memcached build does not support (check phpinfo() / Memcached::getResultMessage)
4. Keep 'client' minimal (timeouts/retry only) and let Phalcon's failover defaults stand

Example fix

// before
new Libmemcached($factory, ['client' => ['connect_timeout' => 50]]); // string key -> setOptions fails

// after
new Libmemcached($factory, ['client' => [\Memcached::OPT_CONNECT_TIMEOUT => 50]]);

// preflight every client option on a throwaway connection
$probe = new \Memcached();
foreach ($client as $key => $value) {
    if (!$probe->setOption($key, $value)) {
        throw new InvalidArgumentException("Memcached rejects client option {$key}");
    }
}

try {
    $cache->get('warmup');
} catch (\Phalcon\Storage\Exceptions\InvalidConfiguration $e) {
    // surface at boot with the offending 'client' map attached
    $logger->critical('Memcached client options rejected: ' . json_encode($client));
    throw $e;
}

When it happens

Trigger: A 'client' entry using string keys instead of \Memcached::OPT_* constants; a value the extension build rejects — e.g. \Memcached::OPT_SERIALIZER_IGBINARY without igbinary support, OPT_COMPRESSION with a non-bool, or an option constant unknown to the installed libmemcached version.

Common situations: Copying 'client' config between servers with different ext-memcached/libmemcached builds; enabling igbinary or json serializers the extension was not compiled with; typos in option names in YAML/PHP config; upgrading the extension so a previously valid option disappears.

Related errors

• Cannot connect to the Memcached server(s)
• 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/1eb8b448e6b46921. Report an issue: GitHub.