What causes "Could not select alternate Redis database ID" in getgrav/grav?

Run redis-cli -h HOST -p PORT -a 'PASSWORD' SELECT N to confirm the exact index is allowed; also check CONFIG GET databases on a self-managed server.

getgrav/grav · warning · RedisException

Could not select alternate Redis database ID

Error message

Could not select alternate Redis database ID

What it means

After a successful Redis connection and optional authentication, Grav calls select() when system.cache.redis.database is a truthy value. If Redis refuses the database ID, Grav throws RedisException and its catch block falls back to the filesystem adapter while logging the reason.

Source

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

                        $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';
                }
                break;

            case 'array':
                $adapter = new ArrayAdapter($defaultLifetime, false);

View on GitHub (pinned to 6040efed04)

Solutions

Run redis-cli -h HOST -p PORT -a 'PASSWORD' SELECT N to confirm the exact index is allowed; also check CONFIG GET databases on a self-managed server.
Set system.cache.redis.database to 0 or remove the key when the deployment uses only the default database.
Correct the value to an integer in the permitted 0..databases-1 range and clear Grav's cached configuration.
For managed or clustered Redis that disallows SELECT, keep the database at 0 and use separate instances or key prefixes for isolation.
Restart PHP/FPM after correcting environment-based configuration.

Example fix

# before (user/config/system.yaml)
cache:
  driver: redis
  redis:
    database: 32 # server has only 16 databases

# after
cache:
  driver: redis
  redis:
    database: 2 # valid 0..15 on this server

Defensive patterns

Strategy: validation

Validate before calling

$redis = new Redis();
$redis->connect($host, $port);
if ($password) {
    $redis->auth($password);
}
if ($databaseId && !$redis->select((int) $databaseId)) {
    throw new RuntimeException('Redis rejected database ' . $databaseId . '; use 0 or a permitted index.');
}
$redis->close();

Try / catch

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

Prevention

Check CONFIG GET databases before choosing an index.
Treat managed Redis as database 0 unless its provider documents SELECT support.
Validate cache configuration per environment.
Clear Grav's cached configuration after changing Redis settings.
Alert when a deployment permanently falls back from Redis to file cache.

When it happens

Trigger: Configure system.cache.redis.driver=redis and system.cache.redis.database to an index outside the server's configured range, an index denied by ACL, or a value sent to a cluster/proxy that does not permit SELECT. Cache.php:399-401 throws and lines 405-409 install the file adapter instead.

Common situations: Copying a database number from an environment with 32 databases to one using the Redis default of 16, using database 16 or higher, typos such as an unintended positive value, managed Redis that exposes only DB 0, or ACL restrictions.

Related errors

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