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

FileStore::flushLocks recursively deletes the lock directory contents but only when a separate lock store is configured. When locks share the cache directory, flushing locks would delete cache files, so the operation is refused. hasSeparateLockStore() is true only when a distinct lockDirectory was provided at construction.

Solutions

Configure a separate lock path in the file cache store config: set 'lock_path' => storage_path('framework/locks') in config/cache.php.
Set CACHE_LOCK_STORE env to a distinct store (e.g., 'redis') to separate lock storage entirely.
If only specific locks need clearing, manually delete lock files from storage_path('framework/data') matching the lock key, or call $lock->release() on held lock instances.

Example fix

// before (config/cache.php)
'stores' => [
    'file' => [
        'driver' => 'file',
        'path' => storage_path('framework/cache/data'),
        // no lock_path
    ],
],

// after
'stores' => [
    'file' => [
        'driver' => 'file',
        'path' => storage_path('framework/cache/data'),
        'lock_path' => storage_path('framework/cache/locks'),
    ],
],

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Set 'lock_path' in the file cache store config when locks are needed.
For multi-server setups, prefer redis/database for locks over the file driver.
Use Cache::lock()->release() for individual lock cleanup instead of flushLocks().

When it happens

Trigger: Calling Cache::store('file')->flushLocks() when the file cache store was constructed without a separate 'lock_path' / lock directory. Occurs when CACHE_LOCK_STORE is unset and the default file driver is used for both cache and locks.

Common situations: Admin script clearing stuck file locks during incident response. Test teardown calling Cache::flushLocks() with the file driver. Production on shared hosting where the file cache is used and locks are co-located.

Related errors

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

Appendix: source

Thrown at src/Illuminate/Cache/FileStore.php:370

            if (! $deleted || $this->files->exists($directory)) {
                return false;
            }
        }

        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.');
        }

        if (! $this->files->isDirectory($this->lockDirectory)) {
            return false;
        }

        foreach ($this->files->directories($this->lockDirectory) as $lockDirectory) {
            $deleted = $this->files->deleteDirectory($lockDirectory);

            if (! $deleted || $this->files->exists($lockDirectory)) {
                return false;
            }
        }

        return true;
    }

    /**

View on GitHub (pinned to e0f6eb3518)