{"record":{"id":"2f0a8da93507ca0d","repo":"litedb-org/LiteDB","slug":"0-2f0a8d","errorCode":"0","errorMessage":"This data file is encrypted and needs a password to open","messagePattern":"This data file is encrypted and needs a password to open","errorType":"exception","errorClass":"LiteException","httpStatus":null,"severity":"critical","filePath":"LiteDB/Engine/LiteEngine.cs","lineNumber":106,"sourceCode":"            _systemCollections = new Dictionary<string, SystemCollection>(StringComparer.OrdinalIgnoreCase);\n            _sequences = new ConcurrentDictionary<string, long>(StringComparer.OrdinalIgnoreCase);\n\n            try\n            {\n                // initialize engine state \n                _state = new EngineState(this, _settings);\n\n                // before initilize, try if must be upgrade\n                if (_settings.Upgrade) this.TryUpgrade();\n\n                // initialize disk service (will create database if needed)\n                _disk = new DiskService(_settings, _state, MEMORY_SEGMENT_SIZES);\n\n                // read page with no cache ref (has a own PageBuffer) - do not Release() support\n                var buffer = _disk.ReadFull(FileOrigin.Data).First();\n\n                // if first byte are 1 this datafile are encrypted but has do defined password to open\n                if (buffer[0] == 1) throw new LiteException(0, \"This data file is encrypted and needs a password to open\");\n\n                // read header database page\n                _header = new HeaderPage(buffer);\n\n                // if database is set to invalid state, need rebuild\n                if (buffer[HeaderPage.P_INVALID_DATAFILE_STATE] != 0 && _settings.AutoRebuild)\n                {\n                    // dispose disk access to rebuild process\n                    _disk.Dispose();\n                    _disk = null;\n\n                    // rebuild database, create -backup file and include _rebuild_errors collection\n                    this.Recovery(_header.Pragmas.Collation);\n\n                    // re-initialize disk service\n                    _disk = new DiskService(_settings, _state, MEMORY_SEGMENT_SIZES);\n\n                    // read buffer header page again","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Engine/LiteEngine.cs#L88-L124","documentation":"Thrown during engine Open() when the first byte of the data file is 0x01, indicating the file is AES-encrypted, but no password was supplied in EngineSettings/LiteDatabase connection string. The disk service reads the raw header page; byte 0 == 1 is the encryption marker. Without the password the AesStream cannot be constructed, so the engine refuses to open.","triggerScenarios":"Opening a LiteDB file that was created with a password, but the current open attempt omits the Password setting or connection string 'password=' key. Also happens if a user copies an encrypted DB and tries to open it without credentials.","commonSituations":"Deploying an app that created the DB with encryption but the production config omits the password; transferring encrypted DBs between environments; wrong assumption that the file is unencrypted.","solutions":["Supply the correct password via EngineSettings.Password or the connection string password= key.","If the password is lost, the data is unrecoverable — restore from an unencrypted backup.","If you intended to create an unencrypted DB, create a new file without a password.","Store the password in a secure secrets manager and inject it into settings."],"exampleFix":"// before — no password\nvar db = new LiteDatabase(\"Filename=secure.db\"); // throws if file is encrypted\n\n// after — supply password\nvar db = new LiteDatabase(\"Filename=secure.db;Password=mySecret\");\n// or via settings\nvar settings = new EngineSettings { Filename = \"secure.db\", Password = \"mySecret\" };","handlingStrategy":"validation","validationCode":"public LiteDatabase OpenDatabase(string filename, string password)\n{\n    // Check the first byte to detect encryption before opening.\n    using (var fs = File.OpenRead(filename))\n    {\n        var first = fs.ReadByte();\n        if (first == 1 && string.IsNullOrEmpty(password))\n            throw new InvalidOperationException(\"File is encrypted but no password was supplied.\");\n    }\n    return new LiteDatabase($\"Filename={filename};Password={password}\");\n}","typeGuard":"static bool IsEncryptedFile(string filename)\n{\n    using var fs = File.OpenRead(filename);\n    return fs.ReadByte() == 1;\n}","tryCatchPattern":"try\n{\n    return new LiteDatabase(connectionString);\n}\ncatch (LiteException ex) when (ex.Message.Contains(\"encrypted and needs a password\"))\n{\n    throw new UnauthorizedAccessException(\"The database file is encrypted. Supply the correct Password.\", ex);\n}","preventionTips":["Store the DB password in a secrets manager (never in source control).","At startup, detect encryption via the first byte and prompt for a password if needed.","Document which environments use encrypted DBs.","Keep unencrypted backups in a secure location for recovery."],"tags":["encryption","authentication","initialization","litedb-engine"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}