{"record":{"id":"ab5825b2da741e7a","repo":"litedb-org/LiteDB","slug":"shared-mode-is-not-supported-in-platforms-that-do","errorCode":null,"errorMessage":"Shared mode is not supported in platforms that do not implement named mutex.","messagePattern":"Shared mode is not supported in platforms that do not implement named mutex\\.","errorType":"exception","errorClass":"PlatformNotSupportedException","httpStatus":null,"severity":"critical","filePath":"LiteDB/Client/Shared/SharedEngine.cs","lineNumber":35,"sourceCode":"\n        public SharedEngine(EngineSettings settings)\n        {\n            _settings = settings;\n\n            var name = SharedMutexNameFactory.Create(settings.Filename, settings.SharedMutexNameStrategy);\n\n            try\n            {\n                _mutex = SharedMutexFactory.Create(name);\n            }\n            catch (NotSupportedException ex)\n            {\n                if (ex is PlatformNotSupportedException)\n                {\n                    throw;\n                }\n\n                throw new PlatformNotSupportedException(\"Shared mode is not supported in platforms that do not implement named mutex.\", ex);\n            }\n        }\n\n        /// <summary>\n        /// Open database in safe mode\n        /// </summary>\n        /// <returns>true if successfully opened; false if already open</returns>\n        private bool OpenDatabase()\n        {\n            try\n            {\n                // Acquire mutex for every call to open DB.\n                _mutex.WaitOne();\n            }\n            catch (AbandonedMutexException) { }\n\n            // Don't create a new engine while a transaction is running.\n            if (!_transactionRunning && _engine == null)","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Shared/SharedEngine.cs#L17-L53","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Switch to Direct mode: set Connection = ConnectionType.Direct (or omit the connection key).","If you need multi-process access, run on a platform that supports named mutexes (desktop .NET on Windows/Linux/macOS).","For single-process apps, Direct mode is sufficient and avoids the mutex entirely."],"exampleFix":"// before\nvar cs = new ConnectionString\n{\n    Filename = \"MyData.db\",\n    Connection = ConnectionType.Shared\n};\n// after\nvar cs = new ConnectionString\n{\n    Filename = \"MyData.db\",\n    Connection = ConnectionType.Direct\n};","handlingStrategy":"try-catch","validationCode":"// Detect shared mode compatibility before opening\ndetectPlatformSupportsNamedMutex();\nvoid detectPlatformSupportsNamedMutex()\n{\n    try { var m = Mutex.OpenExisting(\"Global\\\\test_liteDB_probe\"); m.Dispose(); }\n    catch (WaitHandleCannotBeOpenedException) { /* OK — creation path will be tested */ }\n    catch (NotSupportedException) { /* Shared mode will fail */ }\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    using var db = new LiteDatabase(cs);\n}\ncatch (PlatformNotSupportedException ex) when (ex.Message.Contains(\"Shared mode\"))\n{\n    // Fall back to Direct mode\n    cs.Connection = ConnectionType.Direct;\n    using var db = new LiteDatabase(cs);\n}","preventionTips":["Default to ConnectionType.Direct unless you specifically need cross-process access.","On restricted platforms (Blazor WASM, some mobile), never use Shared mode.","Document the platform requirements for Shared mode in your deployment guide."],"tags":["shared-mode","mutex","platform","connection-string"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}