{"record":{"id":"f0d09aefca4e1311","repo":"laravel/framework","slug":"flushing-locks-is-only-supported-when-the-lock-sto-f0d09a","errorCode":null,"errorMessage":"Flushing locks is only supported when the lock store is separate from the cache store.","messagePattern":"Flushing locks is only supported when the lock store is separate from the cache store\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"warning","filePath":"src/Illuminate/Cache/FileStore.php","lineNumber":370,"sourceCode":"            if (! $deleted || $this->files->exists($directory)) {\n                return false;\n            }\n        }\n\n        return true;\n    }\n\n    /**\n     * Remove all locks from the store.\n     *\n     * @return bool\n     *\n     * @throws \\RuntimeException\n     */\n    public function flushLocks(): bool\n    {\n        if (! $this->hasSeparateLockStore()) {\n            throw new RuntimeException('Flushing locks is only supported when the lock store is separate from the cache store.');\n        }\n\n        if (! $this->files->isDirectory($this->lockDirectory)) {\n            return false;\n        }\n\n        foreach ($this->files->directories($this->lockDirectory) as $lockDirectory) {\n            $deleted = $this->files->deleteDirectory($lockDirectory);\n\n            if (! $deleted || $this->files->exists($lockDirectory)) {\n                return false;\n            }\n        }\n\n        return true;\n    }\n\n    /**","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Cache/FileStore.php#L352-L388","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (config/cache.php)\n'stores' => [\n    'file' => [\n        'driver' => 'file',\n        'path' => storage_path('framework/cache/data'),\n        // no lock_path\n    ],\n],\n\n// after\n'stores' => [\n    'file' => [\n        'driver' => 'file',\n        'path' => storage_path('framework/cache/data'),\n        'lock_path' => storage_path('framework/cache/locks'),\n    ],\n],","handlingStrategy":"validation","validationCode":"// Validate the file store has separate lock storage before flushing\n$store = Cache::store('file')->getStore();\nif (! $store->hasSeparateLockStore()) {\n    return;\n}\n$store->flushLocks();","typeGuard":"function fileStoreHasSeparateLockStore(\\Illuminate\\Cache\\FileStore $store): bool\n{\n    return $store->hasSeparateLockStore();\n}","tryCatchPattern":null,"preventionTips":["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()."],"tags":["cache","file","locks","configuration"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}