laravel/framework · warning · RuntimeException

Flushing locks is only supported when the lock store is…

Error message

Flushing locks is only supported when the lock store is separate from the cache store.

What it means

RedisStore::flushLocks runs FLUSHDB on the lock connection but only when a separate lock connection is configured. Without a separate connection, FLUSHDB would wipe all cached data on the shared Redis database. hasSeparateLockStore() is true only when a distinct lockConnection was injected at construction.

Solutions

Configure a separate lock connection in the redis cache store config: set 'lock_connection' => 'cache-locks' in config/cache.php and define that connection in config/database.php REDIS_CACHE_LOCKS_*.
Set CACHE_LOCK_STORE env to a distinct store name (e.g., 'redis-locks') configured as its own store.
If only specific locks need clearing, release them via $lock->release() or scan/delete lock keys by prefix instead of FLUSHDB.

Example fix

// before (config/cache.php)
'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
        // no lock_connection
    ],
],

// after
'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
        'lock_connection' => 'cache-locks',
    ],
],
// In config/database.php:
'redis_clusters' => [],
'default' => [...],
'cache' => ['host' => env('REDIS_HOST'), ...],
'cache-locks' => [
    'host' => env('REDIS_LOCK_HOST', env('REDIS_HOST')),
    'password' => env('REDIS_LOCK_PASSWORD', env('REDIS_PASSWORD')),
    // dedicated DB number, e.g., 1
    'database' => env('REDIS_LOCK_DB', 1),
],

Defensive patterns

Strategy: validation

Validate before calling

// Validate the redis store has separate lock storage before flushing
$store = Cache::store('redis')->getStore();
if (! $store->hasSeparateLockStore()) {
    return;
}
$store->flushLocks();

Type guard

function redisStoreHasSeparateLockStore(\Illuminate\Cache\RedisStore $store): bool
{
    return $store->hasSeparateLockStore();
}

Prevention

Configure 'lock_connection' in the redis cache store config when locks are needed on Redis.
Use a dedicated Redis DB number (e.g., database => 1) for locks to isolate FLUSHDB blast radius.
Set CACHE_LOCK_STORE env to a distinct configured store.
For targeted cleanup, release individual locks via $lock->release() instead of flushLocks().

When it happens

Trigger: Calling Cache::store('redis')->flushLocks() when the redis cache store was constructed without a separate 'lock_connection'. Occurs when the cache config omits lock_connection or CACHE_LOCK_STORE is unset.

Common situations: Operational script clearing locks on a Redis-backed cache during incident response. CI pipeline teardown calling Cache::flushLocks() on redis driver. Multi-tenant app reusing the same Redis database for cache and locks to save connections.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/9ad59716178314c0. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Cache/RedisStore.php:313

     */
    public function flush()
    {
        $this->connection()->flushdb();

        return true;
    }

    /**
     * Remove all locks from the store.
     *
     * @return bool
     *
     * @throws \RuntimeException
     */
    public function flushLocks(): bool
    {
        if (! $this->hasSeparateLockStore()) {
            throw new RuntimeException('Flushing locks is only supported when the lock store is separate from the cache store.');
        }

        $this->lockConnection()->flushdb();

        return true;
    }

    /**
     * Remove all expired tag set entries.
     *
     * @return void
     */
    public function flushStaleTags()
    {
        foreach ($this->currentTags()->chunk(1000) as $tags) {
            $this->tags($tags->all())->flushStale();
        }
    }

View on GitHub (pinned to e0f6eb3518)