{"record":{"id":"25431cf8a581de6b","repo":"walkor/workerman","slug":"please-install-redis-extension","errorCode":null,"errorMessage":"Please install redis extension.","messagePattern":"Please install redis extension\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Protocols/Http/Session/RedisSessionHandler.php","lineNumber":69,"sourceCode":"    protected static ?Pool $pool = null;\n\n    /**\n     * RedisSessionHandler constructor.\n     * @param array $config = [\n     *  'host'     => '127.0.0.1',\n     *  'port'     => 6379,\n     *  'timeout'  => 2,\n     *  'auth'     => '******',\n     *  'database' => 2,\n     *  'prefix'   => 'redis_session_',\n     *  'ping'     => 55,\n     * ]\n     * @throws RedisException\n     */\n    public function __construct(array $config)\n    {\n        if (false === extension_loaded('redis')) {\n            throw new RuntimeException('Please install redis extension.');\n        }\n\n        $config['timeout'] ??= 2;\n        $this->config = $config;\n    }\n\n    /**\n     * Get connection.\n     * @return Redis\n     * @throws Throwable\n     */\n    protected function connection(): Redis|RedisCluster\n    {\n        // Cannot switch fibers in current execution context when PHP < 8.4\n        if (Worker::$eventLoopClass === Fiber::class && PHP_VERSION_ID < 80400) {\n            if (!$this->connection) {\n                $this->connection = $this->createRedisConnection($this->config);\n                Timer::delay($this->config['pool']['heartbeat_interval'] ?? 55, function () {","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/walkor/workerman/blob/1391112a61d23020e11e7b89f17050f6cfaea431/src/Protocols/Http/Session/RedisSessionHandler.php#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nphp -m | grep redis   # (empty)\n# ... using RedisSessionHandler -> Please install redis extension.\n\n# after\nsudo apt install php-redis        # or: pecl install redis\necho 'extension=redis.so' >> $(php --ini | grep 'Loaded Configuration' | awk '{print $4}')\nphp -m | grep redis               # redis\n# then restart workerman","handlingStrategy":"validation","validationCode":"if (!extension_loaded('redis')) {\n    throw new RuntimeException('ext-redis required for Redis sessions; install it or choose another handler');\n}\n$handler = new RedisSessionHandler($config);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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)"],"tags":["php","workerman","redis","session","php-extension"],"backgroundTag":"missing-php-extension","analyzedSha":"1391112a61d23020e11e7b89f17050f6cfaea431","analyzedAt":"2026-08-21T02:05:46.744Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}