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

DatabaseStore::flushLocks deletes all rows from the cache locks table but only when the lock store is separate from the cache store (different DB connection/table). When locks share the cache table, flushing locks would delete cache entries, so the operation is refused. hasSeparateLockStore() is true only when a separate lock connection or lock table was provided.

Solutions

Configure a separate lock store by setting 'lock_connection' and/or 'lock_table' in the database cache store config in config/cache.php.
Set CACHE_LOCK_STORE env to point at a distinct cache store (e.g., 'redis') so hasSeparateLockStore() returns true.
If you only need to clear specific locks, release them via $lock->release() or DB::table('cache_locks')->where('key', $key)->delete() instead of flushLocks().

Example fix

// before (config/cache.php)
'stores' => [
    'database' => [
        'driver' => 'database',
        'table' => 'cache',
        'connection' => null,
        // no lock_connection/lock_table
    ],
],

// after
'stores' => [
    'database' => [
        'driver' => 'database',
        'table' => 'cache',
        'connection' => null,
        'lock_connection' => null,
        'lock_table' => 'cache_locks',
    ],
],
// Run: php artisan cache:table && php artisan migrate

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Always configure 'lock_table' (and optionally 'lock_connection') when using the database cache driver.
Run php artisan cache:table to publish both cache and cache_locks migrations.
Document that flushLocks() requires the separate lock table configuration.
Use Cache::lock()->release() for targeted cleanup instead of flushLocks().

When it happens

Trigger: Calling Cache::store('database')->flushLocks() when the database cache store was constructed without a separate lock_table or lock_connection. Common when CACHE_LOCK_STORE is not set and the default database cache driver is reused for locks.

Common situations: Test or admin script calling Cache::flushLocks() to clear stuck locks while using the database cache driver without a dedicated locks table. Production using the same database table for cache and locks (the default) to save migrations.

Related errors

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

Appendix: source

Thrown at src/Illuminate/Cache/DatabaseStore.php:465

     */
    public function flush()
    {
        $this->table()->delete();

        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->lockTable()->delete();

        return true;
    }

    /**
     * Get a query builder for the cache table.
     *
     * @return \Illuminate\Database\Query\Builder
     */
    protected function table()
    {
        return $this->connection->table($this->table);
    }

    /**

View on GitHub (pinned to e0f6eb3518)