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

ArrayStore::flushLocks removes all in-memory locks but only when a separate lock store is configured. When locks share the same ArrayStore as the cache (the default), flushing locks would also wipe cache entries, so the operation is refused. hasSeparateLockStore() returns false unless a distinct lock store was injected at construction.

Solutions

Construct the ArrayStore with a separate lock store: new ArrayStore($lockStore = new ArrayStore()) so hasSeparateLockStore() returns true.
Use Cache::forget() or release individual locks via $lock->release() instead of flushLocks() when using the array driver.
Switch to a driver with native lock separation (redis, database) for the production path that needs flushLocks().

Example fix

// before
$store = new ArrayStore();
$store->flushLocks(); // RuntimeException

// after
$cacheStore = new ArrayStore();
$lockStore = new ArrayStore();
$store = new ArrayStore(lockStore: $lockStore);
// hasSeparateLockStore() now true
$store->flushLocks();

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

When using the array driver in tests that exercise locks, construct it with a separate lock store.
Document that flushLocks() requires a separate lock store at construction time.
Default to release() per lock rather than flushLocks() for cleanup in test teardown.

When it happens

Trigger: Calling Cache::store('array')->flushLocks() or Cache::flushLocks() against an ArrayStore that was constructed without a separate lock store. Common in tests using CACHE_DRIVER=array and asserting lock cleanup behavior.

Common situations: Test suite asserts Cache::flushLocks() to reset state between tests with array driver. Production code defensively flushes locks but the array driver is used for caching with locks co-located.

Related errors

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

Appendix: 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 e0f6eb3518)