litedb-org/LiteDB · critical · LiteException

0

0

Error message

This data file is encrypted and needs a password to open

What it means

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.

Source

Thrown at LiteDB/Engine/LiteEngine.cs:106

            _systemCollections = new Dictionary<string, SystemCollection>(StringComparer.OrdinalIgnoreCase);
            _sequences = new ConcurrentDictionary<string, long>(StringComparer.OrdinalIgnoreCase);

            try
            {
                // initialize engine state 
                _state = new EngineState(this, _settings);

                // before initilize, try if must be upgrade
                if (_settings.Upgrade) this.TryUpgrade();

                // initialize disk service (will create database if needed)
                _disk = new DiskService(_settings, _state, MEMORY_SEGMENT_SIZES);

                // read page with no cache ref (has a own PageBuffer) - do not Release() support
                var buffer = _disk.ReadFull(FileOrigin.Data).First();

                // if first byte are 1 this datafile are encrypted but has do defined password to open
                if (buffer[0] == 1) throw new LiteException(0, "This data file is encrypted and needs a password to open");

                // read header database page
                _header = new HeaderPage(buffer);

                // if database is set to invalid state, need rebuild
                if (buffer[HeaderPage.P_INVALID_DATAFILE_STATE] != 0 && _settings.AutoRebuild)
                {
                    // dispose disk access to rebuild process
                    _disk.Dispose();
                    _disk = null;

                    // rebuild database, create -backup file and include _rebuild_errors collection
                    this.Recovery(_header.Pragmas.Collation);

                    // re-initialize disk service
                    _disk = new DiskService(_settings, _state, MEMORY_SEGMENT_SIZES);

                    // read buffer header page again

View on GitHub (pinned to f906a5f850)

Solutions

1. Supply the correct password via EngineSettings.Password or the connection string password= key.
2. If the password is lost, the data is unrecoverable — restore from an unencrypted backup.
3. If you intended to create an unencrypted DB, create a new file without a password.
4. Store the password in a secure secrets manager and inject it into settings.

Example fix

// before — no password
var db = new LiteDatabase("Filename=secure.db"); // throws if file is encrypted

// after — supply password
var db = new LiteDatabase("Filename=secure.db;Password=mySecret");
// or via settings
var settings = new EngineSettings { Filename = "secure.db", Password = "mySecret" };

public LiteDatabase OpenDatabase(string filename, string password)
{
    // Check the first byte to detect encryption before opening.
    using (var fs = File.OpenRead(filename))
    {
        var first = fs.ReadByte();
        if (first == 1 && string.IsNullOrEmpty(password))
            throw new InvalidOperationException("File is encrypted but no password was supplied.");
    }
    return new LiteDatabase($"Filename={filename};Password={password}");
}

static bool IsEncryptedFile(string filename)
{
    using var fs = File.OpenRead(filename);
    return fs.ReadByte() == 1;
}

try
{
    return new LiteDatabase(connectionString);
}
catch (LiteException ex) when (ex.Message.Contains("encrypted and needs a password"))
{
    throw new UnauthorizedAccessException("The database file is encrypted. Supply the correct Password.", ex);
}

When it happens

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

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

Related errors

• EngineSettings must have Filename or DataStream as data sour
• ENTITY_INITIALIZATION_FAILED
• 0
• Extend expression must return a document
• 0

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