yiisoft/yii2 · error · InvalidConfigException

MemCache requires PHP $extension extension to be loaded.

Error message

MemCache requires PHP $extension extension to be loaded.

What it means

Thrown by yii\caching\MemCache::getMemcache() when the PHP extension backing the component is not loaded in the current process: it checks extension_loaded() for 'memcached' or 'memcache' depending on the useMemcached flag. The component deliberately fails at first use rather than silently caching nowhere. The two extensions are distinct PECL packages with different APIs, so the flag must match the extension that is actually installed.

Source

Thrown at framework/caching/MemCache.php:222

                    $server->retryInterval,
                    $server->status,
                    $server->failureCallback
                );
            }
        }
    }

    /**
     * Returns the underlying memcache (or memcached) object.
     * @return \Memcache|\Memcached the memcache (or memcached) object used by this cache component.
     * @throws InvalidConfigException if memcache or memcached extension is not loaded
     */
    public function getMemcache()
    {
        if ($this->_cache === null) {
            $extension = $this->useMemcached ? 'memcached' : 'memcache';
            if (!extension_loaded($extension)) {
                throw new InvalidConfigException("MemCache requires PHP $extension extension to be loaded.");
            }

            if ($this->useMemcached) {
                $this->_cache = $this->persistentId !== null ? new \Memcached($this->persistentId) : new \Memcached();
                if ($this->username !== null || $this->password !== null) {
                    $this->_cache->setOption(\Memcached::OPT_BINARY_PROTOCOL, true);
                    $this->_cache->setSaslAuthData($this->username, $this->password);
                }
                if (!empty($this->options)) {
                    $this->_cache->setOptions($this->options);
                }
            } else {
                $this->_cache = new \Memcache();
            }
        }

        return $this->_cache;
    }

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Install and enable the matching extension: apt-get install php-memcached (or pecl install memcached / pecl install memcache), then restart php-fpm and verify with php -m | grep memcache.
2. Make useMemcached match what is installed: true requires ext-memcached, false requires ext-memcache.
3. If you cannot install extensions, switch the cache component to one without extension needs (FileCache, DbCache) or Redis with predis.
4. In Docker/CI images, add the extension in the build (docker-php-ext-install / install-php-extensions) and confirm for both web and CLI SAPIs.

Example fix

// before
// host has neither ext-memcache nor ext-memcached
'cache' => ['class' => \yii\caching\MemCache::class], // throws on first cache use

// after (option 1: install the extension)
// $ apt-get install -y php-memcached && systemctl restart php8.2-fpm
// $ php -m | grep memcached
'cache' => ['class' => \yii\caching\MemCache::class, 'useMemcached' => true],

// after (option 2: no extension possible)
'cache' => ['class' => \yii\caching\FileCache::class],

// At boot, before the cache component is first used
$extension = $useMemcached ? 'memcached' : 'memcache';
if (!extension_loaded($extension)) {
    throw new \RuntimeException("PHP extension '{$extension}' is required by the MemCache component.");
    // or degrade: use \yii\caching\FileCache as a temporary cache backend
}

try {
    Yii::$app->cache->get('warmup');
} catch (\yii\base\InvalidConfigException $e) {
    // memcache(d) missing in this SAPI: fail the deploy check loudly
    throw new \RuntimeException('Cache backend unavailable: ' . $e->getMessage(), 0, $e);
}

When it happens

Trigger: Configuring the cache component as MemCache on a host without ext-memcache; setting useMemcached = true while only the old memcache extension (or neither) is installed; deploying to a container/Docker image built without the extension; extension present but not enabled for the SAPI in use (php-fpm vs CLI differ — migrations/console commands fail while web works); opcode/JIT or phpbrew environments missing the .so load.

Common situations: Works on the dev machine, fails in CI or production because the Docker image lacks php-memcached; php-fpm has the extension but CLI (used by yii migrate) does not; switching a project from memcache to memcached without updating installs; Alpine/special PHP builds where the package was never added.

Related errors

• The 'host' property must be specified for every memcache ser
• Encryption requires the OpenSSL PHP extension
• The view file does not exist: $viewFile
• DbDependency::sql must be set.
• "{class}::$query" should be an instance of "yii\db\QueryInte

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/89fd93fde5e85b53. Report an issue: GitHub.