What causes "Redis authentication failed" in getgrav/grav?

Verify the exact credentials from the same host with redis-cli -h HOST -p PORT -a 'PASSWORD' PING (or the configured socket) and correct user/config/system.yaml.

getgrav/grav · warning · RedisException

Redis authentication failed

Error message

Redis authentication failed

What it means

While building the Redis cache adapter, Grav connects with the configured socket or server and then calls phpredis auth() when system.cache.redis.password is truthy. If Redis rejects the credentials and auth() returns false, Grav throws RedisException. The surrounding catch records the reason and falls back to the filesystem cache, so pages usually keep working but without Redis.

Source

Thrown at system/src/Grav/Common/Cache.php:395

                if (extension_loaded('redis')) {
                    $redis = new \Redis();
                    try {
                        $socket = $this->config->get('system.cache.redis.socket', false);
                        $password = $this->config->get('system.cache.redis.password', false);
                        $databaseId = $this->config->get('system.cache.redis.database', 0);

                        if ($socket) {
                            $redis->connect($socket);
                        } else {
                            $redis->connect(
                                $this->config->get('system.cache.redis.server', 'localhost'),
                                $this->config->get('system.cache.redis.port', 6379)
                            );
                        }

                        // Authenticate with password if set
                        if ($password && !$redis->auth($password)) {
                            throw new \RedisException('Redis authentication failed');
                        }

                        // Select alternate ( !=0 ) database ID if set
                        if ($databaseId && !$redis->select($databaseId)) {
                            throw new \RedisException('Could not select alternate Redis database ID');
                        }

                        $adapter = new RedisAdapter($redis, $namespace, $defaultLifetime);
                        $resolved_driver_name = 'redis';
                    } catch (Throwable $e) {
                        $this->logCacheFallback($driver_name, 'file', $e->getMessage());
                        $adapter = $this->createFilesystemAdapter($namespace, $defaultLifetime);
                        $resolved_driver_name = 'file';
                    }
                } else {
                    $this->logCacheFallback($driver_name, 'file', 'Redis extension not installed');
                    $adapter = $this->createFilesystemAdapter($namespace, $defaultLifetime);
                    $resolved_driver_name = 'file';

View on GitHub (pinned to 6040efed04)

Solutions

Verify the exact credentials from the same host with redis-cli -h HOST -p PORT -a 'PASSWORD' PING (or the configured socket) and correct user/config/system.yaml.
Use the password for Redis's default user or patch the authentication call to use the phpredis username/password form; the current Grav code passes only a password.
Quote the YAML password when it contains special characters, and clear Grav's cached configuration after changing it.
Restart PHP/FPM and the web server so the updated configuration and environment are used.
Inspect the fallback log entry; if Redis is optional, size the filesystem cache for the resulting load instead of leaving repeated auth failures.

Example fix

# before (user/config/system.yaml)
cache:
  driver: redis
  redis:
    server: 127.0.0.1
    port: 6379
    password: old-password

# after
cache:
  driver: redis
  redis:
    server: 127.0.0.1
    port: 6379
    password: 'correct-password'

Defensive patterns

Strategy: validation

Validate before calling

$redis = new Redis();
$connected = $socket ? $redis->connect($socket) : $redis->connect($host, $port);
if (!$connected || ($password && !$redis->auth($password))) {
    throw new RuntimeException('Redis credentials rejected; fix system.cache.redis.password.');
}
$redis->close();

Try / catch

try {
    $cache = new RedisAdapter($redis, $namespace, $lifetime);
} catch (RedisException $e) {
    error_log('Redis unavailable; using filesystem cache: ' . $e->getMessage());
    $cache = new FilesystemAdapter($namespace, $lifetime, $cacheDir);
}

Prevention

Run an AUTH plus PING health check before enabling Redis in production.
Keep Redis credentials in environment-specific configuration and rotate deliberately.
Quote YAML passwords containing punctuation.
Watch Grav cache-fallback logs during deployment.
Remember this Grav path sends a password only, not a Redis ACL username.

When it happens

Trigger: Set system.cache.redis.driver to redis with the redis extension loaded and a non-empty system.cache.redis.password, then supply a wrong password, a password for the wrong Redis user, or credentials from a stale environment. The failed auth at Cache.php:394-396 triggers the fallback at Cache.php:405-409.

Common situations: Password rotation, an unquoted YAML value that parses differently, a Redis 6 ACL named user while this code path sends only a password, environment-specific credentials, or a proxy/managed Redis that requires a different authentication mechanism.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of getgrav/grav@6040efed04 (2026-08-17). Data as JSON: /api/errors/c894122a80bdf08a. Report an issue: GitHub.