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

ArrayStore::flushLocks() throws if hasSeparateLockStore() is false. The ArrayStore is an in-memory store typically used in tests; its hasSeparateLockStore() normally returns true, so this guard exists for the contract case where the store is wrapped/configured to share a single backing store with locks. Flushing only locks is unsafe when they live in the same storage as cache values.

Source

Thrown at src/Illuminate/Cache/ArrayStore.php:238

     */
    public function flush()
    {
        $this->storage = [];

        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->locks = [];

        return true;
    }

    /**
     * Get the cache key prefix.
     *
     * @return string
     */
    public function getPrefix()
    {
        return '';
    }

    /**

View on GitHub (pinned to bd6b5437e6)

Solutions

If you need lock-only flushing on ArrayStore, ensure hasSeparateLockStore() returns true (the default) so the lock array is flushed independently.
If using a subclass, override hasSeparateLockStore() to return true when locks are stored in a distinct property.
If the store genuinely shares storage, call flush() to clear everything instead of flushLocks().

Example fix

// before
$store = new ArrayStore();
// (subclass forced hasSeparateLockStore() = false)
$store->flushLocks(); // throws

// after
$store->flush(); // clears both values and locks
// or ensure hasSeparateLockStore() returns true in your subclass

Defensive patterns

Strategy: validation

Validate before calling

$store = Cache::store('array')->getStore();
if (method_exists($store, 'hasSeparateLockStore') && ! $store->hasSeparateLockStore()) {
    // do not call flushLocks(); use flush() instead
    Cache::store('array')->flush();
} else {
    $store->flushLocks();
}

Type guard

function canFlushLocksSeparately(\Illuminate\Contracts\Cache\Store $store): bool
{
    return $store instanceof \Illuminate\Contracts\Cache\CanFlushLocks
        && (! method_exists($store, 'hasSeparateLockStore') || $store->hasSeparateLockStore());
}

Try / catch

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

Prevention

Check hasSeparateLockStore() before flushLocks().
In tests use flush() to clear state.
Avoid subclassing ArrayStore with a non-separating lock store.

When it happens

Trigger: Calling Cache::store('array')->getStore()->flushLocks() on an ArrayStore whose hasSeparateLockStore() was overridden to false (e.g. a subclass), or invoking flushLocks() through a path that does not honor the separation. In vanilla ArrayStore this is effectively unreachable because hasSeparateLockStore() returns true.

Common situations: Subclassing ArrayStore for tests and overriding hasSeparateLockStore(). Misconfiguring a custom in-memory store. Indirectly hitting the shared CanFlushLocks contract via a wrapper.

Related errors

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