symfony/symfony · error · CacheException

MemcachedAdapter client error: %s

Error message

MemcachedAdapter client error: %s

What it means

Thrown by MemcachedAdapter::checkResultCode() after a Memcached operation returns a result code other than RES_SUCCESS or RES_NOTFOUND. The message embeds the lowercased libmemcached result message (replacing %s), so it surfaces the underlying client failure (e.g. connection refused, write failure, partial timeout, server marked dead).

Source

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

        }

        return $ok;
    }

    protected function doClear(string $namespace): bool
    {
        return '' === $namespace && $this->getClient()->flush();
    }

    private function checkResultCode(mixed $result): mixed
    {
        $code = $this->client->getResultCode();

        if (\Memcached::RES_SUCCESS === $code || \Memcached::RES_NOTFOUND === $code) {
            return $result;
        }

        throw new CacheException('MemcachedAdapter client error: '.strtolower($this->client->getResultMessage()));
    }

    private function getClient(): \Memcached
    {
        if (isset($this->client)) {
            return $this->client;
        }

        $opt = $this->lazyClient->getOption(\Memcached::OPT_SERIALIZER);
        if (\Memcached::SERIALIZER_PHP !== $opt && \Memcached::SERIALIZER_IGBINARY !== $opt) {
            throw new CacheException('MemcachedAdapter: "serializer" option must be "php" or "igbinary".');
        }
        if ('' !== $prefix = (string) $this->lazyClient->getOption(\Memcached::OPT_PREFIX_KEY)) {
            throw new CacheException(\sprintf('MemcachedAdapter: "prefix_key" option must be empty when using proxified connections, "%s" given.', $prefix));
        }

        return $this->client = $this->lazyClient;
    }

View on GitHub (pinned to 3b11ffbe25)

Solutions

1. Verify the memcached service is running and reachable from the PHP process: telnet host 11211 or nc -z host 11211.
2. Inspect the exact result message in the exception text to map it to a libmemcached RES_* cause and address that specifically.
3. Check container/compose service definitions and env vars point at the correct host/port.
4. If item-too-large, reduce payload size or raise memcached -I (max item size) and -m (memory) on the server.
5. For transient network blips, consider a retry/backoff wrapper or failover pool, but never swallow the exception silently.

Example fix

// before — assume cache always works
$pool->get('key', fn() => expensive());

// after — surface infrastructure problems
try {
    $pool->get('key', fn() => expensive());
} catch (\Symfony\Component\Cache\Exception\CacheException $e) {
    // log full message which includes the libmemcached result text
    $logger->error('Cache failure: '.$e->getMessage());
    throw $e;
}

// preflight reachability before relying on the pool
function memcachedReachable(string $host, int $port=11211): bool {
    $fp = @fsockopen($host, $port, $errno, $errstr, 1);
    if (is_resource($fp)) { fclose($fp); return true; }
    return false;
}

try {
    $item = $pool->get('key', $callback);
} catch (\Symfony\Component\Cache\Exception\CacheException $e) {
    $logger->error('Memcached op failed: '.$e->getMessage());
    // only fall back if you intentionally have a fallback pool
    return $callback();
}

When it happens

Trigger: Any cache operation (save, delete, flush, increment) where $this->client->getResultCode() returns a non-success, non-notfound code — e.g. memcached server is down/unreachable, network partition, item too large, bad key, server flushed/evicted under foot, or libmemcached marking all servers dead.

Common situations: Memcached process not running or restarted (connection errors); firewall/network blocking the 11211 port; persistent_id reuse across clusters; values exceeding memcached item size limit (~1MB); exhausted or evicted memory; deploying without the memcached service in the container/compose setup.

Related errors

• MemcachedAdapter: "prefix_key" option must be empty when usi
• Failed to retrieve master information from sentinel "%s".
• Redis connection failed: {error}.
• Memcached > 3.1.5 is required.
• MemcachedAdapter: "serializer" option must be "php" or "igbi

AI-assisted analysis of symfony/symfony@3b11ffbe25 (2026-08-11). Data as JSON: /api/errors/a49f001f7a6228fd. Report an issue: GitHub.