litedb-org/LiteDB · critical · PlatformNotSupportedException

Shared mode is not supported because named mutex access cont

Error message

Shared mode is not supported because named mutex access control is unavailable on this platform.

What it means

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.

Source

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

        private const string MutexPrefix = "Global\\";
        private const string MutexSuffix = ".Mutex";

        public static Mutex Create(string name)
        {
            var fullName = MutexPrefix + name + MutexSuffix;

            if (!IsWindows())
            {
                return new Mutex(false, fullName);
            }

            try
            {
                return WindowsMutex.Create(fullName);
            }
            catch (Win32Exception ex)
            {
                throw new PlatformNotSupportedException("Shared mode is not supported because named mutex access control is unavailable on this platform.", ex);
            }
            catch (EntryPointNotFoundException ex)
            {
                throw new PlatformNotSupportedException("Shared mode is not supported because named mutex access control is unavailable on this platform.", ex);
            }
            catch (DllNotFoundException ex)
            {
                throw new PlatformNotSupportedException("Shared mode is not supported because named mutex access control is unavailable on this platform.", ex);
            }
        }

#if NET6_0_OR_GREATER
        private static bool IsWindows()
        {
            return OperatingSystem.IsWindows();
        }
#else
        private static bool IsWindows()

View on GitHub (pinned to f906a5f850)

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.

Example fix

// before
var cs = new ConnectionString { Filename = "C:\very\long\path\...\MyData.db", Connection = ConnectionType.Shared };
// after
var cs = new ConnectionString { Filename = "MyData.db", Connection = ConnectionType.Direct };

Defensive patterns

Strategy: try-catch

Validate before calling

// Probe whether Shared mode works before committing to it
bool sharedModeSupported = ProbeSharedMutex();
if (!sharedModeSupported) cs.Connection = ConnectionType.Direct;

bool ProbeSharedMutex()
{
    try
    {
        var probeName = $"Global\\LiteDB_Probe_{Guid.NewGuid():N}";
        var m = new Mutex(false, probeName);
        m.Dispose();
        return true;
    }
    catch { return false; }
}

Try / catch

try
{
    using var db = new LiteDatabase(cs); // Connection = Shared
}
catch (PlatformNotSupportedException ex) when (ex.Message.Contains("named mutex"))
{
    var win32 = ex.InnerException as Win32Exception;
    // Log win32?.NativeErrorCode for diagnosis
    cs.Connection = ConnectionType.Direct;
    using var db = new LiteDatabase(cs);
}

Prevention

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.

When it happens

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

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

Related errors

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