{"id":"056faab9f8801173","repo":"laravel/framework","slug":"unable-to-acquire-file-lock-at-path-this-path","errorCode":null,"errorMessage":"Unable to acquire file lock at path [{$this->path}].","messagePattern":"Unable to acquire file lock at path \\[(.+?)\\]\\.","errorType":"exception","errorClass":"LockTimeoutException","httpStatus":null,"severity":"warning","filePath":"src/Illuminate/Filesystem/LockableFile.php","lineNumber":134,"sourceCode":"        rewind($this->handle);\n\n        ftruncate($this->handle, 0);\n\n        return $this;\n    }\n\n    /**\n     * Get a shared lock on the file.\n     *\n     * @param  bool  $block\n     * @return $this\n     *\n     * @throws \\Illuminate\\Contracts\\Filesystem\\LockTimeoutException\n     */\n    public function getSharedLock($block = false)\n    {\n        if (! flock($this->handle, LOCK_SH | ($block ? 0 : LOCK_NB))) {\n            throw new LockTimeoutException(\"Unable to acquire file lock at path [{$this->path}].\");\n        }\n\n        $this->isLocked = true;\n\n        return $this;\n    }\n\n    /**\n     * Get an exclusive lock on the file.\n     *\n     * @param  bool  $block\n     * @return $this\n     *\n     * @throws \\Illuminate\\Contracts\\Filesystem\\LockTimeoutException\n     */\n    public function getExclusiveLock($block = false)\n    {\n        if (! flock($this->handle, LOCK_EX | ($block ? 0 : LOCK_NB))) {","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Filesystem/LockableFile.php#L116-L152","documentation":"Thrown by LockableFile::getSharedLock() when PHP's flock() with LOCK_SH fails (returns false). A shared (reader) lock cannot be acquired because another process holds an exclusive lock, or the underlying OS call failed. The exception (Illuminate\\Contracts\\Filesystem\\LockTimeoutException) carries the file path so the contention point is identifiable. With $block=false (default) it uses LOCK_NB so it fails immediately rather than waiting.","triggerScenarios":"Calling ->getSharedLock() on a LockableFile (used by cache stores, atomic file locks, debounce locks) while another worker holds an exclusive lock on the same path. Commonly reached through File cache driver, file-based locks with Cache::lock(), or concurrent queue workers reading a shared lock-protected resource.","commonSituations":"Multiple queue workers racing on the same cache file. Stale lock files left behind by a crashed worker. NFS/network filesystems where flock semantics are unreliable. High-concurrency local-cache setups during traffic spikes.","solutions":["Retry the operation with backoff — locks are typically transient contention.","Pass block=true to wait blocking-style instead of failing fast, if a short wait is acceptable.","Ensure crashed workers release locks; clean stale lock files in storage/framework/cache or storage/framework/sessions.","Switch the cache/lock store from 'file' to 'redis' or 'database' for multi-worker workloads.","Verify the lock directory is on a local filesystem (not NFS) when using flock."],"exampleFix":"// before\n$lock = (new LockableFile($path, 'r'))->getSharedLock();\n\n// after\nuse Illuminate\\Contracts\\Filesystem\\LockTimeoutException;\n\ntry {\n    $lock = (new LockableFile($path, 'r'))->getSharedLock(block: true);\n} catch (LockTimeoutException $e) {\n    // backoff and retry, or fall back to cache store\n    usleep(100_000);\n    return retry(3, fn () => (new LockableFile($path, 'r'))->getSharedLock(), 100);\n}","handlingStrategy":"retry","validationCode":"// No pure pre-check guarantees a lock is acquirable, but you can reduce contention:\nif (! file_exists($path)) {\n    abort(503, 'Lock target does not exist: '.$path);\n}","typeGuard":"// No type guard applies to a runtime flock outcome; the relevant check is the exception type.\nfunction isLockTimeout(\\Throwable $e): bool {\n    return $e instanceof \\Illuminate\\Contracts\\Filesystem\\LockTimeoutException;\n}","tryCatchPattern":"use Illuminate\\Contracts\\Filesystem\\LockTimeoutException;\n\ntry {\n    $lock = (new \\Illuminate\\Filesystem\\LockableFile($path, 'r'))->getSharedLock();\n} catch (LockTimeoutException $e) {\n    // retry with backoff, or pass block: true to wait\n}","preventionTips":["Prefer Cache::lock() (redis/database) over file locks for multi-worker apps.","Keep critical sections short to minimize lock hold time.","Use block: true when a brief wait is acceptable to avoid immediate failure.","Avoid placing lock files on NFS/network filesystems."],"tags":["filesystem","locking","flock","concurrency","lock-timeout"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}