What causes "Please install redis extension." in walkor/workerman?

Install phpredis: 'pecl install redis' or 'apt install php-redis', add extension=redis.so to the CLI php.ini, and verify with 'php -m | grep redis'

walkor/workerman · error · RuntimeException

Please install redis extension.

Error message

Please install redis extension.

What it means

RedisSessionHandler's constructor hard-requires the phpredis extension (ext-redis) because it type-hints Redis|RedisCluster. If extension_loaded('redis') is false it throws immediately, before any connection attempt.

Source

Thrown at src/Protocols/Http/Session/RedisSessionHandler.php:69

    protected static ?Pool $pool = null;

    /**
     * RedisSessionHandler constructor.
     * @param array $config = [
     *  'host'     => '127.0.0.1',
     *  'port'     => 6379,
     *  'timeout'  => 2,
     *  'auth'     => '******',
     *  'database' => 2,
     *  'prefix'   => 'redis_session_',
     *  'ping'     => 55,
     * ]
     * @throws RedisException
     */
    public function __construct(array $config)
    {
        if (false === extension_loaded('redis')) {
            throw new RuntimeException('Please install redis extension.');
        }

        $config['timeout'] ??= 2;
        $this->config = $config;
    }

    /**
     * Get connection.
     * @return Redis
     * @throws Throwable
     */
    protected function connection(): Redis|RedisCluster
    {
        // Cannot switch fibers in current execution context when PHP < 8.4
        if (Worker::$eventLoopClass === Fiber::class && PHP_VERSION_ID < 80400) {
            if (!$this->connection) {
                $this->connection = $this->createRedisConnection($this->config);
                Timer::delay($this->config['pool']['heartbeat_interval'] ?? 55, function () {

View on GitHub (pinned to 1391112a61)

Solutions

Install phpredis: 'pecl install redis' or 'apt install php-redis', add extension=redis.so to the CLI php.ini, and verify with 'php -m | grep redis'
Restart the Workerman processes after enabling the extension (they are long-lived, they never pick up ini changes on their own)
If you cannot install the extension, use a different session handler that does not depend on it

Example fix

# before
php -m | grep redis   # (empty)
# ... using RedisSessionHandler -> Please install redis extension.

# after
sudo apt install php-redis        # or: pecl install redis
echo 'extension=redis.so' >> $(php --ini | grep 'Loaded Configuration' | awk '{print $4}')
php -m | grep redis               # redis
# then restart workerman

Defensive patterns

Strategy: validation

Validate before calling

if (!extension_loaded('redis')) {
    throw new RuntimeException('ext-redis required for Redis sessions; install it or choose another handler');
}
$handler = new RedisSessionHandler($config);

Prevention

Add ext-redis to the deployment checklist / Docker image for any service using Redis sessions
Verify with 'php -m | grep redis' using the same PHP binary that runs Workerman (CLI SAPI)

When it happens

Trigger: Configuring the HTTP session handler to RedisSessionHandler on a host without phpredis; container images built without the extension; the extension enabled for the web SAPI php.ini but not for CLI, which is the SAPI Workerman runs under.

Common situations: Deploying to a slim Docker image; a new environment where 'apt install php-redis' was done for fpm but the CLI php.ini has no extension=redis.so; switching session handler to Redis on a machine where only predis is installed.

Related errors

AI-assisted analysis of walkor/workerman@1391112a61 (2026-08-21). Data as JSON: /api/errors/25431cf8a581de6b. Report an issue: GitHub.