litedb-org/LiteDB · critical · Win32Exception

Failed to create shared mutex with global access.

Error message

Failed to create shared mutex with global access.

What it means

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).

Source

Thrown at LiteDB/Client/Shared/SharedMutexFactory.cs:80

                try
                {
                    if (!NativeMethods.ConvertStringSecurityDescriptorToSecurityDescriptor(WorldAccessSecurityDescriptor, SddlRevision1, out descriptor, out _))
                    {
                        throw new Win32Exception(Marshal.GetLastWin32Error(), "Failed to create security descriptor for shared mutex.");
                    }

                    var attributes = new NativeMethods.SECURITY_ATTRIBUTES
                    {
                        nLength = (uint)Marshal.SizeOf<NativeMethods.SECURITY_ATTRIBUTES>(),
                        bInheritHandle = 0,
                        lpSecurityDescriptor = descriptor
                    };

                    var handle = NativeMethods.CreateMutexEx(ref attributes, name, 0, NativeMethods.MUTEX_ALL_ACCESS);

                    if (handle == IntPtr.Zero || handle == NativeMethods.InvalidHandleValue)
                    {
                        throw new Win32Exception(Marshal.GetLastWin32Error(), "Failed to create shared mutex with global access.");
                    }

                    var mutex = new Mutex();
                    mutex.SafeWaitHandle = new SafeWaitHandle(handle, ownsHandle: true);

                    return mutex;
                }
                finally
                {
                    if (descriptor != IntPtr.Zero)
                    {
                        NativeMethods.LocalFree(descriptor);
                    }
                }
            }
        }

        private static class NativeMethods

View on GitHub (pinned to f906a5f850)

Solutions

1. Switch to Direct mode.
2. Run the application with elevated privileges if the process needs a Global mutex.
3. Check if another process or session owns the Global mutex name and release it.
4. Consult ex.NativeErrorCode from the Win32Exception for the precise failure reason.

Example fix

// No code fix for native handle failure; use Direct mode
var cs = new ConnectionString { Connection = ConnectionType.Direct };

// Probe mutex creation with MUTEX_ALL_ACCESS before using Shared mode
try
{
    using var probe = new Mutex(false, $"Global\\LiteDB_probe_{Guid.NewGuid():N}");
}
catch { cs.Connection = ConnectionType.Direct; }

try
{
    using var db = new LiteDatabase(cs);
}
catch (Win32Exception ex) when (ex.Message.Contains("shared mutex with global access"))
{
    // CreateMutexEx returned invalid handle; use Direct mode
    cs.Connection = ConnectionType.Direct;
    using var db = new LiteDatabase(cs);
}

When it happens

Trigger: connection=Shared on Windows when the security descriptor was created successfully but CreateMutexEx still fails. The handle is IntPtr.Zero or InvalidHandleValue (-1).

Common situations: 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.

Related errors

• Shared mode is not supported because named mutex access cont
• Failed to create security descriptor for shared mutex.
• Shared mode is not supported in platforms that do not implem

AI-assisted analysis of litedb-org/LiteDB@f906a5f850 (2026-08-13). Data as JSON: /api/errors/04a43f28479ff048. Report an issue: GitHub.