phalcon/cphalcon · error · Phalcon\Storage\Exceptions\ConnectionFailed

{underlying exception message}

Error message

{underlying exception message}

What it means

Redis\Adapter::checkConnect() wraps the phpredis connect()/pconnect() call in try/catch; any \Exception (typically RedisException) is rethrown as Phalcon\Storage\Exceptions\ConnectionFailed carrying the underlying message verbatim — e.g. 'Connection refused', 'php_network_getaddresses: getaddrinfo failed' (DNS), 'Connection timed out', or a TLS handshake error from the 'ssl' context options.

Source

Thrown at phalcon/Storage/Adapter/Redis.zep:444

        } else {
            let method       = "pconnect",
                persistentId = this->options["persistentId"],
                parameter    = !empty(persistentId) ? persistentId : "persistentId" . options["index"];
        }

        /** @var storage_redis_context $connectionOptions */
        try {
            let result = connection->{method}(
                host,
                port,
                timeout,
                parameter,
                retryInterval,
                readTimeout,
                connectionOptions
            );
        } catch \Exception, ex {
            throw new ConnectionFailed(ex->getMessage());
        }

        if !result {
            throw new ConnectionFailed(
                sprintf(
                    "Could not connect to the Redis server [%s:%s]",
                    host,
                    port
                )
            );
        }

        return this;
    }

    /**
     * @throws DatabaseSelectionFailed
     */

View on GitHub (pinned to b7419de9cd)

Solutions

1. Read getMessage(): it is the underlying phpredis error and names the cause
2. Test reachability from the app container/host: redis-cli -h <host> -p <port> PING
3. For DNS errors verify resolution: getent hosts <host>
4. Increase 'timeout' and 'readTimeout' for slow links; fix 'ssl' context options (verify_peer, local_cert paths)
5. Catch ConnectionFailed at the cache boundary and degrade gracefully (see try-catch pattern)

Example fix

// before
new Redis($factory, ['host' => 'redus']); // typo -> getaddrinfo failed

// after
new Redis($factory, ['host' => 'redis', 'port' => 6379]);

// preflight before the first cache call in a request
$host = $options['host'] ?? '127.0.0.1';
$port = (int) ($options['port'] ?? 6379);
$sock = @fsockopen($host, $port, $errno, $errstr, 0.5);
if ($sock === false) {
    throw new RuntimeException("Redis unreachable at {$host}:{$port}: {$errstr}");
}
fclose($sock);

// decorate the cache with retry + fallback
$attempts = 3;
while (true) {
    try {
        return $cache->get($key);
    } catch (\Phalcon\Storage\Exceptions\ConnectionFailed $e) {
        // $e->getMessage() is the phpredis error (refused, DNS, timeout)
        if (--$attempts <= 0) {
            $logger->error('Redis down: ' . $e->getMessage());
            return $default; // or rethrow
        }
        usleep(250_000 * (4 - $attempts)); // backoff
    }
}

When it happens

Trigger: redis-server not running or wrong 'port' (connection refused); wrong 'host' hostname (getaddrinfo failed / name resolution); 'timeout' too small for slow networks; 'ssl' options with bad cert paths or peer verification failures; pconnect() on a stale persistent socket.

Common situations: Docker/compose where the cache service name is misspelled or the app starts before redis; firewall dropping SYNs so connects time out; TLS misconfiguration when moving to rediss://; IPv6-only DNS in the cluster.

Related errors

• Could not connect to the Redis server [%s:%s]
• Could not connect to the Redis Cluster server due to: {excep
• Failed to authenticate with the Redis server
• Redis server selected database failed
• Cannot set Memcached client options

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/e72033bb204b6287. Report an issue: GitHub.