{"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/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Cache/FileStore.php#L352-L388","documentation":"FileStore::flushLocks() throws if hasSeparateLockStore() is false, i.e. when lockDirectory is null or equals the cache directory. Without a distinct lock directory, flushing only locks would require distinguishing lock files from cache files, which the store does not support.","triggerScenarios":"Configuring a file cache store without 'lock_path', then calling Cache::store('file')->getStore()->flushLocks() or cache:clear-locks. The guard fires whenever lockDirectory is null or identical to the main directory.","commonSituations":"Default file store config omits lock_path. Sharing one cache directory for both values and locks. Older Laravel upgrades where lock_path did not exist.","solutions":["Add 'lock_path' => storage_path('framework/cache/locks') (different from 'path') in the file store config.","Ensure the lock directory exists and is writable (chmod, storage:bootstrap).","If a single directory is intentional, call flush() to clear everything instead of flushLocks()."],"exampleFix":"// before\n'file' => [\n    'driver' => 'file',\n    'path' => storage_path('framework/cache/data'),\n    // no lock_path -> flushLocks throws\n],\n\n// after\n'file' => [\n    'driver' => 'file',\n    'path' => storage_path('framework/cache/data'),\n    'lock_path' => storage_path('framework/cache/locks'),\n],","handlingStrategy":"validation","validationCode":"$store = Cache::store('file')->getStore();\nif ($store instanceof \\Illuminate\\Cache\\FileStore && ! $store->hasSeparateLockStore()) {\n    throw new \\RuntimeException('File cache requires a distinct lock_path to flushLocks().');\n}\n$store->flushLocks();","typeGuard":"function fileCacheHasSeparateLocks(\\Illuminate\\Contracts\\Cache\\Store $store): bool\n{\n    return $store instanceof \\Illuminate\\Cache\\FileStore\n        && $store->hasSeparateLockStore();\n}","tryCatchPattern":"try {\n    Cache::store('file')->getStore()->flushLocks();\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'lock store is separate')) {\n        Cache::store('file')->flush();\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Configure lock_path in every file cache store.","Ensure the lock directory is writable.","Guard hasSeparateLockStore() before flushLocks().","Run storage:bootstrap / chmod in deployment."],"tags":["cache","file-store","locks","configuration"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}