{"record":{"id":"93277a4bea9e092c","repo":"microsoft/aspire","slug":"failed-to-acquire-file-lock-lockpath-within-timeout","errorCode":null,"errorMessage":"Failed to acquire file lock '{lockPath}' within {timeout.TotalSeconds:F0} seconds.","messagePattern":"Failed to acquire file lock '(.+?)' within (.+?) seconds\\.","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"warning","filePath":"src/Shared/FileLock.cs","lineNumber":74,"sourceCode":"    /// <param name=\"timeout\">Maximum time to wait for the lock.</param>\n    /// <returns>A <see cref=\"FileLock\"/> that releases the lock when disposed.</returns>\n    /// <exception cref=\"TimeoutException\">Thrown if the lock cannot be acquired within the timeout period.</exception>\n    public static FileLock Acquire(string lockPath, TimeSpan timeout)\n    {\n        var deadline = DateTime.UtcNow + timeout;\n        CreateLockDirectory(lockPath);\n\n        while (true)\n        {\n            try\n            {\n                return new FileLock(CreateLockStream(lockPath));\n            }\n            catch (Exception exception) when (exception is IOException or UnauthorizedAccessException)\n            {\n                if (DateTime.UtcNow >= deadline)\n                {\n                    throw new TimeoutException($\"Failed to acquire file lock '{lockPath}' within {timeout.TotalSeconds:F0} seconds.\", exception);\n                }\n            }\n\n            Thread.Sleep(s_defaultRetryDelay);\n        }\n    }\n\n    /// <summary>\n    /// Attempts to acquire an exclusive file lock without waiting.\n    /// </summary>\n    public static FileLock? TryAcquire(string lockPath)\n    {\n        try\n        {\n            return Acquire(lockPath);\n        }\n        catch (Exception exception) when (exception is IOException or UnauthorizedAccessException)\n        {","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Shared/FileLock.cs#L56-L92","documentation":"The synchronous FileLock.Acquire retries creating/opening the lock file while another process holds it. If every attempt fails with IOException or UnauthorizedAccessException until the deadline expires, it throws TimeoutException wrapping the last underlying exception, indicating the lock could not be obtained within the timeout.","triggerScenarios":"Calling FileLock.Acquire(lockPath, timeout) while another process holds the lock for the entire timeout period, or the lock file cannot be created due to filesystem permissions or transient OS locks (antivirus, backup).","commonSituations":"Two AppHost/dashboard processes contending for a shared cache or settings file; a stale lock left by a crashed process; running under a read-only directory or restricted account; AV software briefly holding new files.","solutions":["Increase the timeout argument if contention is expected to be short-lived","Check for and remove stale lock files at lockPath left by crashed processes","Fix filesystem permissions on the lock directory so the process can create files","Investigate the wrapped inner exception (via TimeoutException.InnerException) for the real cause (sharing violation vs access denied)","Ensure the other lock holder releases promptly — look for long-lived FileLock instances not disposed"],"exampleFix":"// before\nusing var lockFile = FileLock.Acquire(lockPath, TimeSpan.FromSeconds(5));\n// after\ntry\n{\n    using var lockFile = FileLock.Acquire(lockPath, TimeSpan.FromSeconds(30));\n}\ncatch (TimeoutException ex)\n{\n    logger.LogError(ex.InnerException, \"Could not acquire lock {LockPath}\", lockPath);\n    return;\n}","handlingStrategy":"retry","validationCode":"// Check writability of the lock directory before attempting the lock\nnew FileInfo(Path.Combine(lockDir, \"probe.tmp\")).Directory?.Create();\nusing (var probe = File.Create(Path.Combine(lockDir, \"probe.tmp\"))) { }","typeGuard":null,"tryCatchPattern":"try { using var l = FileLock.Acquire(lockPath, TimeSpan.FromSeconds(30)); /* work */ }\ncatch (TimeoutException ex) { logger.LogError(ex.InnerException, \"Lock {Path} busy\", lockPath); }","preventionTips":["Dispose FileLock promptly, including on exceptions","Choose timeouts proportional to expected critical-section duration","Clean up stale lock files after crashes","Run under an account with write access to the lock directory"],"tags":["file-lock","timeout","concurrency","filesystem"],"backgroundTag":"request-timeout","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}