laravel/framework · warning · RuntimeException

Flushing locks is only supported when the lock store is sepa

Error message

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

What it means

DatabaseStore::flushLocks() throws if hasSeparateLockStore() is false, which occurs when the lock table name equals the cache table name ($this->lockTable === $this->table). Flushing only locks is destructive when cache rows and lock rows share one table; the guard prevents wiping cache data.

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 bd6b5437e6)

Solutions

  1. Set a distinct 'lock_table' (default 'cache_locks') in config/cache.php so hasSeparateLockStore() returns true.
  2. Optionally set a separate 'lock_connection' to put locks on a different DB connection entirely.
  3. Run the migration php artisan cache:table / php artisan cache:locks-table to create the dedicated locks table.
  4. If you intentionally share one table, call flush() to clear everything rather than flushLocks().

Example fix

// before
'stores' => [
    'db' => [
        'driver' => 'database',
        'table' => 'cache',
        'lock_table' => 'cache', // same table -> throws
    ],
],

// after
'stores' => [
    'db' => [
        'driver' => 'database',
        'table' => 'cache',
        'lock_table' => 'cache_locks',
        'lock_connection' => null,
    ],
],
Defensive patterns

Strategy: validation

Validate before calling

$store = Cache::store('db')->getStore();
if ($store instanceof \Illuminate\Cache\DatabaseStore && ! $store->hasSeparateLockStore()) {
    throw new \RuntimeException('Database cache lock_table must differ from cache table to flushLocks().');
}
$store->flushLocks();

Type guard

function databaseCacheHasSeparateLocks(\Illuminate\Contracts\Cache\Store $store): bool
{
    return $store instanceof \Illuminate\Cache\DatabaseStore
        && $store->hasSeparateLockStore();
}

Try / catch

try {
    Cache::store('db')->getStore()->flushLocks();
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'lock store is separate')) {
        Cache::store('db')->flush();
    } else {
        throw $e;
    }
}

Prevention

When it happens

Trigger: Configuring a database cache store with 'lock_table' set to the same value as 'table' (e.g. both 'cache'), then calling Cache::store('db')->getStore()->flushLocks() or any code path that invokes it (e.g. the Artisan cache:clear-locks command).

Common situations: Setting lock_table => 'cache' to reuse the migrations' cache table for locks. Omitting lock_table and having previously renamed the cache table to 'cache_locks'. Migrating an older app where locks were stored alongside cache entries.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/263a8b06702e388e.json. Report an issue: GitHub.