{"record":{"id":"1eb8b448e6b46921","repo":"phalcon/cphalcon","slug":"cannot-set-memcached-client-options","errorCode":null,"errorMessage":"Cannot set Memcached client options","messagePattern":"Cannot set Memcached client options","errorType":"exception","errorClass":"Phalcon\\Storage\\Exceptions\\InvalidConfiguration","httpStatus":null,"severity":"error","filePath":"phalcon/Storage/Adapter/Libmemcached.zep","lineNumber":274,"sourceCode":"\n        return this->getAdapter()\n                   ->set(\n                       key,\n                       this->getSerializedData(value),\n                       this->getTtl(ttl)\n                   )\n        ;\n    }\n\n    /**\n     * @phpstan-param storage_libmemcached_client $client\n     *\n     * @throws InvalidConfiguration\n     */\n    private function setOptions(<\\Memcached> connection, array client) -> <static>\n    {\n        if (true !== connection->setOptions(client)) {\n            throw new InvalidConfiguration(\n                \"Cannot set Memcached client options\"\n            );\n        }\n\n        return this;\n    }\n\n    private function setSasl(\n        <\\Memcached> connection,\n        string saslUser,\n        string saslPass\n    ) -> <static> {\n        if (true !== empty(saslUser)) {\n            connection->setSaslAuthData(saslUser, saslPass);\n        }\n\n        return this;\n    }","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Storage/Adapter/Libmemcached.zep#L256-L292","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use \\Memcached::OPT_* constant keys and verify each value's type against the extension docs","Bisect the offending option with a throwaway instance: foreach ($client as $k => $v) { var_dump($k, (new \\Memcached())->setOption($k, $v)); }","Remove options your ext-memcached build does not support (check phpinfo() / Memcached::getResultMessage)","Keep 'client' minimal (timeouts/retry only) and let Phalcon's failover defaults stand"],"exampleFix":"// before\nnew Libmemcached($factory, ['client' => ['connect_timeout' => 50]]); // string key -> setOptions fails\n\n// after\nnew Libmemcached($factory, ['client' => [\\Memcached::OPT_CONNECT_TIMEOUT => 50]]);","handlingStrategy":"try-catch","validationCode":"// preflight every client option on a throwaway connection\n$probe = new \\Memcached();\nforeach ($client as $key => $value) {\n    if (!$probe->setOption($key, $value)) {\n        throw new InvalidArgumentException(\"Memcached rejects client option {$key}\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    $cache->get('warmup');\n} catch (\\Phalcon\\Storage\\Exceptions\\InvalidConfiguration $e) {\n    // surface at boot with the offending 'client' map attached\n    $logger->critical('Memcached client options rejected: ' . json_encode($client));\n    throw $e;\n}","preventionTips":["Use \\Memcached::OPT_* constants as keys; never string names","Keep 'client' minimal and let Phalcon defaults stand","Re-verify the option list after upgrading ext-memcached or libmemcached"],"tags":["php","phalcon","memcached","cache","configuration"],"backgroundTag":"invalid-config-option","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}