{"record":{"id":"04a43f28479ff048","repo":"litedb-org/LiteDB","slug":"failed-to-create-shared-mutex-with-global-access","errorCode":null,"errorMessage":"Failed to create shared mutex with global access.","messagePattern":"Failed to create shared mutex with global access\\.","errorType":"exception","errorClass":"Win32Exception","httpStatus":null,"severity":"critical","filePath":"LiteDB/Client/Shared/SharedMutexFactory.cs","lineNumber":80,"sourceCode":"                try\n                {\n                    if (!NativeMethods.ConvertStringSecurityDescriptorToSecurityDescriptor(WorldAccessSecurityDescriptor, SddlRevision1, out descriptor, out _))\n                    {\n                        throw new Win32Exception(Marshal.GetLastWin32Error(), \"Failed to create security descriptor for shared mutex.\");\n                    }\n\n                    var attributes = new NativeMethods.SECURITY_ATTRIBUTES\n                    {\n                        nLength = (uint)Marshal.SizeOf<NativeMethods.SECURITY_ATTRIBUTES>(),\n                        bInheritHandle = 0,\n                        lpSecurityDescriptor = descriptor\n                    };\n\n                    var handle = NativeMethods.CreateMutexEx(ref attributes, name, 0, NativeMethods.MUTEX_ALL_ACCESS);\n\n                    if (handle == IntPtr.Zero || handle == NativeMethods.InvalidHandleValue)\n                    {\n                        throw new Win32Exception(Marshal.GetLastWin32Error(), \"Failed to create shared mutex with global access.\");\n                    }\n\n                    var mutex = new Mutex();\n                    mutex.SafeWaitHandle = new SafeWaitHandle(handle, ownsHandle: true);\n\n                    return mutex;\n                }\n                finally\n                {\n                    if (descriptor != IntPtr.Zero)\n                    {\n                        NativeMethods.LocalFree(descriptor);\n                    }\n                }\n            }\n        }\n\n        private static class NativeMethods","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Shared/SharedMutexFactory.cs#L62-L98","documentation":"Thrown inside WindowsMutex.Create when CreateMutexEx returns a null or invalid (-1) handle, meaning the named mutex with MUTEX_ALL_ACCESS and the security attributes could not be created. The last Win32 error code reveals why (e.g., ERROR_ALREADY_EXISTS is not an error here, but ERROR_ACCESS_DENIED or ERROR_INVALID_HANDLE would be).","triggerScenarios":"connection=Shared on Windows when the security descriptor was created successfully but CreateMutexEx still fails. The handle is IntPtr.Zero or InvalidHandleValue (-1).","commonSituations":"Insufficient privileges to create a mutex with MUTEX_ALL_ACCESS. A mutex with the same Global name owned by a different session/user. Group policy or security software preventing global mutex creation. Running in a terminal services / RDP session where Global prefix requires special permissions.","solutions":["Switch to Direct mode.","Run the application with elevated privileges if the process needs a Global mutex.","Check if another process or session owns the Global mutex name and release it.","Consult ex.NativeErrorCode from the Win32Exception for the precise failure reason."],"exampleFix":"// No code fix for native handle failure; use Direct mode\nvar cs = new ConnectionString { Connection = ConnectionType.Direct };","handlingStrategy":"try-catch","validationCode":"// Probe mutex creation with MUTEX_ALL_ACCESS before using Shared mode\ntry\n{\n    using var probe = new Mutex(false, $\"Global\\\\LiteDB_probe_{Guid.NewGuid():N}\");\n}\ncatch { cs.Connection = ConnectionType.Direct; }","typeGuard":null,"tryCatchPattern":"try\n{\n    using var db = new LiteDatabase(cs);\n}\ncatch (Win32Exception ex) when (ex.Message.Contains(\"shared mutex with global access\"))\n{\n    // CreateMutexEx returned invalid handle; use Direct mode\n    cs.Connection = ConnectionType.Direct;\n    using var db = new LiteDatabase(cs);\n}","preventionTips":["Run the process with privileges sufficient for Global mutex creation.","Check for conflicting mutex names from other processes/sessions.","Default to Direct mode in sandboxed or RDP environments."],"tags":["shared-mode","mutex","win32","create-mutex","windows"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}