walkor/workerman · error · RuntimeException

Redis connect {$config['host']}:{$config['port']} fail.

Error message

Redis connect {$config['host']}:{$config['port']} fail.

What it means

RedisSessionHandler::createRedisConnection() calls Redis::connect($config['host'], $config['port'], $config['timeout']) and throws a RuntimeException naming the host:port when the connection cannot be established (older phpredis returns false; newer versions throw RedisException themselves before this check). The config array is whatever you passed to the handler.

Source

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

                    $obj = new \stdClass();
                    Context::set('context.onDestroy', $obj);
                }
                DestructionWatcher::watch($obj, $closure);
            }
        }
        return $connection;
    }

    /**
     * Create redis connection.
     * @param array $config
     * @return Redis
     */
    protected function createRedisConnection(array $config): Redis|RedisCluster
    {
        $redis = new Redis();
        if (false === $redis->connect($config['host'], $config['port'], $config['timeout'])) {
            throw new RuntimeException("Redis connect {$config['host']}:{$config['port']} fail.");
        }
        if (!empty($config['auth'])) {
            $redis->auth($config['auth']);
        }
        if (!empty($config['database'])) {
            $redis->select((int)$config['database']);
        }
        if (empty($config['prefix'])) {
            $config['prefix'] = 'redis_session_';
        }
        $redis->setOption(Redis::OPT_PREFIX, $config['prefix']);
        return $redis;
    }

    /**
     * {@inheritdoc}
     */
    public function open(string $savePath, string $name): bool

View on GitHub (pinned to 1391112a61)

Solutions

  1. Verify reachability from the same host: redis-cli -h <host> -p <port> ping
  2. Check the config array keys passed to RedisSessionHandler are exactly host, port, timeout, auth, database, prefix
  3. Fix environment: start Redis, open the firewall/port, raise 'timeout', use the correct docker network name, or enable TLS settings

Example fix

// before
$config = ['address' => '10.0.0.5:6379']; // wrong keys -> host/port missing
new RedisSessionHandler($config);

// after
$config = ['host' => '10.0.0.5', 'port' => 6379, 'timeout' => 2, 'auth' => 'secret', 'database' => 0];
new RedisSessionHandler($config);
Defensive patterns

Strategy: retry

Validate before calling

$config = ['host' => '10.0.0.5', 'port' => 6379, 'timeout' => 2];
$probe = @fsockopen($config['host'], (int)$config['port'], $errNo, $errStr, 2);
if ($probe === false) {
    throw new RuntimeException("Redis unreachable at {$config['host']}:{$config['port']}: $errStr");
}
fclose($probe);

Try / catch

try {
    $handler = new RedisSessionHandler($config);
} catch (RuntimeException|RedisException $e) {
    // transient network failure: back off and retry, then fall back to file sessions
    sleep(min(2 ** $attempt, 30));
    return retryOrFallback($e);
}

Prevention

When it happens

Trigger: Redis server stopped or unreachable; wrong host/port keys in the config array (the handler expects 'host' and 'port'); firewall or security group blocking 6379; timeout too small for the network latency; Redis bound to 127.0.0.1 only while the worker connects to an external address.

Common situations: Staging/prod pointing at a Redis that is down; Docker networking mistakes (host 'localhost' instead of the service name); typo'd port; config file using 'server'/'database' style keys instead of 'host'/'port'; cloud Redis requiring TLS so a plain connect fails.

Related errors

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