{"record":{"id":"b67542aef50ebccb","repo":"litedb-org/LiteDB","slug":"shared-mode-is-not-supported-because-named-mutex-a","errorCode":null,"errorMessage":"Shared mode is not supported because named mutex access control is unavailable on this platform.","messagePattern":"Shared mode is not supported because named mutex access control is unavailable on this platform\\.","errorType":"exception","errorClass":"PlatformNotSupportedException","httpStatus":null,"severity":"critical","filePath":"LiteDB/Client/Shared/SharedMutexFactory.cs","lineNumber":29,"sourceCode":"        private const string MutexPrefix = \"Global\\\\\";\n        private const string MutexSuffix = \".Mutex\";\n\n        public static Mutex Create(string name)\n        {\n            var fullName = MutexPrefix + name + MutexSuffix;\n\n            if (!IsWindows())\n            {\n                return new Mutex(false, fullName);\n            }\n\n            try\n            {\n                return WindowsMutex.Create(fullName);\n            }\n            catch (Win32Exception ex)\n            {\n                throw new PlatformNotSupportedException(\"Shared mode is not supported because named mutex access control is unavailable on this platform.\", ex);\n            }\n            catch (EntryPointNotFoundException ex)\n            {\n                throw new PlatformNotSupportedException(\"Shared mode is not supported because named mutex access control is unavailable on this platform.\", ex);\n            }\n            catch (DllNotFoundException ex)\n            {\n                throw new PlatformNotSupportedException(\"Shared mode is not supported because named mutex access control is unavailable on this platform.\", ex);\n            }\n        }\n\n#if NET6_0_OR_GREATER\n        private static bool IsWindows()\n        {\n            return OperatingSystem.IsWindows();\n        }\n#else\n        private static bool IsWindows()","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Shared/SharedMutexFactory.cs#L11-L47","documentation":"Thrown by SharedMutexFactory.Create on Windows when WindowsMutex.Create fails with a Win32Exception — the native P/Invoke call to advapi32.dll or kernel32.dll returned a Win32 error code. The error is wrapped in PlatformNotSupportedException with the original Win32Exception as inner exception. The original error code (accessible via ex.InnerException.NativeErrorCode) reveals the root cause.","triggerScenarios":"connection=Shared on Windows when ConvertStringSecurityDescriptorToSecurityDescriptor or CreateMutexEx returns a Win32 error. Common codes: ERROR_ACCESS_DENIED (5), ERROR_INVALID_PARAMETER (87), ERROR_NOT_ENOUGH_MEMORY (8).","commonSituations":"Running as a low-privilege account that cannot create a Global mutex. Antivirus or security software blocking mutex creation. Very long filenames pushing the mutex name past OS limits. Running in a sandboxed or containerized Windows environment.","solutions":["Switch to Direct mode if multi-process access is not needed.","Inspect ex.InnerException.NativeErrorCode to identify the specific Win32 error and address it (e.g., elevate privileges for ERROR_ACCESS_DENIED).","Use a shorter database filename to avoid exceeding the mutex name length limit.","Run the application outside sandboxed/containerized environments that restrict Global mutex creation."],"exampleFix":"// before\nvar cs = new ConnectionString { Filename = \"C:\\very\\long\\path\\...\\MyData.db\", Connection = ConnectionType.Shared };\n// after\nvar cs = new ConnectionString { Filename = \"MyData.db\", Connection = ConnectionType.Direct };","handlingStrategy":"try-catch","validationCode":"// Probe whether Shared mode works before committing to it\nbool sharedModeSupported = ProbeSharedMutex();\nif (!sharedModeSupported) cs.Connection = ConnectionType.Direct;\n\nbool ProbeSharedMutex()\n{\n    try\n    {\n        var probeName = $\"Global\\\\LiteDB_Probe_{Guid.NewGuid():N}\";\n        var m = new Mutex(false, probeName);\n        m.Dispose();\n        return true;\n    }\n    catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    using var db = new LiteDatabase(cs); // Connection = Shared\n}\ncatch (PlatformNotSupportedException ex) when (ex.Message.Contains(\"named mutex\"))\n{\n    var win32 = ex.InnerException as Win32Exception;\n    // Log win32?.NativeErrorCode for diagnosis\n    cs.Connection = ConnectionType.Direct;\n    using var db = new LiteDatabase(cs);\n}","preventionTips":["Use Direct mode by default; switch to Shared only when multi-process access is confirmed to work.","On Windows, ensure the process account has privileges to create Global mutexes.","Keep database filenames short to avoid mutex name length limits."],"tags":["shared-mode","mutex","win32","windows","platform"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}