symfony/symfony · error · Symfony\Component\Cache\Exception\CacheException

MemcachedAdapter: "serializer" option must be "php" or "igbi

Error message

MemcachedAdapter: "serializer" option must be "php" or "igbinary".

What it means

Thrown by MemcachedAdapter's constructor (MemcachedAdapter.php:58) when the provided \Memcached client's OPT_SERIALIZER is set to something other than SERIALIZER_PHP or SERIALIZER_IGBINARY. The adapter marshals values itself via DefaultMarshaller, so a conflicting client serializer (e.g. JSON) would double-encode and corrupt data.

Source

Thrown at src/Symfony/Component/Cache/Adapter/MemcachedAdapter.php:59

     * Using a RedisAdapter is recommended instead. If you cannot do otherwise, be aware that:
     * - the Memcached::OPT_BINARY_PROTOCOL must be enabled
     *   (that's the default when using MemcachedAdapter::createConnection());
     * - tags eviction by Memcached's LRU algorithm will break by-tags invalidation;
     *   your Memcached memory should be large enough to never trigger LRU.
     *
     * Using a MemcachedAdapter as a pure items store is fine.
     */
    public function __construct(\Memcached $client, string $namespace = '', int $defaultLifetime = 0, ?MarshallerInterface $marshaller = null)
    {
        if (!static::isSupported()) {
            throw new CacheException('Memcached > 3.1.5 is required.');
        }
        $this->maxIdLength = self::MAX_KEY_LENGTH;

        if ('Memcached' === $client::class) {
            $opt = $client->getOption(\Memcached::OPT_SERIALIZER);
            if (\Memcached::SERIALIZER_PHP !== $opt && \Memcached::SERIALIZER_IGBINARY !== $opt) {
                throw new CacheException('MemcachedAdapter: "serializer" option must be "php" or "igbinary".');
            }
            $this->maxIdLength -= \strlen($client->getOption(\Memcached::OPT_PREFIX_KEY));
            $this->client = $client;
        } else {
            $this->lazyClient = $client;
        }

        parent::__construct($namespace, $defaultLifetime);
        $this->enableVersioning();
        $this->marshaller = $marshaller ?? new DefaultMarshaller();
    }

    public static function isSupported(): bool
    {
        return \extension_loaded('memcached') && version_compare(phpversion('memcached'), '3.1.6', '>=');
    }

    /**

View on GitHub (pinned to 698e28026c)

Solutions

1. Reset the serializer before passing the client: $client->setOption(\Memcached::OPT_SERIALIZER, \Memcached::SERIALIZER_PHP);
2. Prefer creating the client via MemcachedAdapter::createConnection() which sets a sane default serializer.
3. If you need JSON serialization, do it in your values before caching, not via the memcached serializer.

Example fix

// before
$client = new \Memcached();
$client->setOption(\Memcached::OPT_SERIALIZER, \Memcached::SERIALIZER_JSON);
new MemcachedAdapter($client);

// after
$client->setOption(\Memcached::OPT_SERIALIZER, \Memcached::SERIALIZER_PHP);
new MemcachedAdapter($client);

$opt = $client->getOption(\Memcached::OPT_SERIALIZER);
if (!in_array($opt, [\Memcached::SERIALIZER_PHP, \Memcached::SERIALIZER_IGBINARY], true)) {
    $client->setOption(\Memcached::OPT_SERIALIZER, \Memcached::SERIALIZER_PHP);
}
new MemcachedAdapter($client);

function hasCompatibleSerializer(\Memcached $c): bool
{
    return in_array($c->getOption(\Memcached::OPT_SERIALIZER), [\Memcached::SERIALIZER_PHP, \Memcached::SERIALIZER_IGBINARY], true);
}

When it happens

Trigger: Constructing `new MemcachedAdapter($client)` where $client->setOption(\Memcached::OPT_SERIALIZER, \Memcached::SERIALIZER_JSON) was called beforehand. Passing a client created by hand instead of via MemcachedAdapter::createConnection().

Common situations: Sharing a Memcached instance between this adapter and legacy code that set SERIALIZER_JSON. A pre-configured client injected via DI that defaults to JSON serialization. Migrating from a custom memcached wrapper that used JSON.

Related errors

• Invalid Memcached DSN: it does not start with "memcached:".
• Invalid Memcached DSN.
• Invalid Memcached DSN: query parameter "host" must be an arr
• Invalid Memcached DSN: missing host or path.
• MemcachedAdapter: "prefix_key" option must be empty when usi

AI-assisted analysis of symfony/symfony@698e28026c (2026-08-06). Data as JSON: /api/errors/97dea32d0717baa0. Report an issue: GitHub.