litedb-org/LiteDB · critical · PlatformNotSupportedException

Shared mode is not supported in platforms that do not implem

Error message

Shared mode is not supported in platforms that do not implement named mutex.

What it means

Thrown by the SharedEngine constructor when SharedMutexFactory.Create raises a NotSupportedException that is not specifically a PlatformNotSupportedException. LiteDB wraps it to give a clear message that the platform lacks named mutex support, which is required for cross-process shared mode coordination.

Source

Thrown at LiteDB/Client/Shared/SharedEngine.cs:35

        public SharedEngine(EngineSettings settings)
        {
            _settings = settings;

            var name = SharedMutexNameFactory.Create(settings.Filename, settings.SharedMutexNameStrategy);

            try
            {
                _mutex = SharedMutexFactory.Create(name);
            }
            catch (NotSupportedException ex)
            {
                if (ex is PlatformNotSupportedException)
                {
                    throw;
                }

                throw new PlatformNotSupportedException("Shared mode is not supported in platforms that do not implement named mutex.", ex);
            }
        }

        /// <summary>
        /// Open database in safe mode
        /// </summary>
        /// <returns>true if successfully opened; false if already open</returns>
        private bool OpenDatabase()
        {
            try
            {
                // Acquire mutex for every call to open DB.
                _mutex.WaitOne();
            }
            catch (AbandonedMutexException) { }

            // Don't create a new engine while a transaction is running.
            if (!_transactionRunning && _engine == null)

View on GitHub (pinned to f906a5f850)

Solutions

1. Switch to Direct mode: set Connection = ConnectionType.Direct (or omit the connection key).
2. If you need multi-process access, run on a platform that supports named mutexes (desktop .NET on Windows/Linux/macOS).
3. For single-process apps, Direct mode is sufficient and avoids the mutex entirely.

Example fix

// before
var cs = new ConnectionString
{
    Filename = "MyData.db",
    Connection = ConnectionType.Shared
};
// after
var cs = new ConnectionString
{
    Filename = "MyData.db",
    Connection = ConnectionType.Direct
};

// Detect shared mode compatibility before opening
detectPlatformSupportsNamedMutex();
void detectPlatformSupportsNamedMutex()
{
    try { var m = Mutex.OpenExisting("Global\\test_liteDB_probe"); m.Dispose(); }
    catch (WaitHandleCannotBeOpenedException) { /* OK — creation path will be tested */ }
    catch (NotSupportedException) { /* Shared mode will fail */ }
}

try
{
    using var db = new LiteDatabase(cs);
}
catch (PlatformNotSupportedException ex) when (ex.Message.Contains("Shared mode"))
{
    // Fall back to Direct mode
    cs.Connection = ConnectionType.Direct;
    using var db = new LiteDatabase(cs);
}

When it happens

Trigger: Opening a database with connection=Shared (or ConnectionType.Shared) on a platform or runtime that cannot create a named system mutex. The inner exception is a NotSupportedException subtype other than PlatformNotSupportedException.

Common situations: Running on a restricted platform (e.g., Blazor WebAssembly, some mobile runtimes) where named mutexes are unavailable. Using connection=Shared in an environment where Direct mode is the only option. Targeting netstandard2.0 on a runtime that lacks named mutex support.

Related errors

• Shared mode is not supported because named mutex access cont
• Failed to create security descriptor for shared mutex.
• Failed to create shared mutex with global access.
• connectionString
• connectionString

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