litedb-org/LiteDB · error · ArgumentException

EngineSettings must have Filename or DataStream as data sour

Error message

EngineSettings must have Filename or DataStream as data source

What it means

Thrown by EngineSettings.CreateDataFactory() when none of the data-source conditions are met: DataStream is null, Filename is not ':memory:', not ':temp:', and not a non-empty string path. The factory cannot create an IStreamFactory without a backing data source, so engine initialization aborts. This is an ArgumentException, not a LiteException.

Source

Thrown at LiteDB/Engine/EngineSettings.cs:102

        {
            if (this.DataStream != null)
            {
                return new StreamFactory(this.DataStream, this.Password);
            }
            else if (this.Filename == ":memory:")
            {
                return new StreamFactory(new MemoryStream(), this.Password);
            }
            else if (this.Filename == ":temp:")
            {
                return new StreamFactory(new TempStream(), this.Password);
            }
            else if (!string.IsNullOrEmpty(this.Filename))
            {
                return new FileStreamFactory(this.Filename, this.Password, this.ReadOnly, false, useAesStream);
            }

            throw new ArgumentException("EngineSettings must have Filename or DataStream as data source");
        }

        /// <summary>
        /// Create new IStreamFactory for logfile
        /// </summary>
        internal IStreamFactory CreateLogFactory()
        {
            if (this.LogStream != null)
            {
                return new StreamFactory(this.LogStream, this.Password);
            }
            else if (this.Filename == ":memory:")
            {
                return new StreamFactory(new MemoryStream(), this.Password);
            }
            else if (this.Filename == ":temp:")
            {
                return new StreamFactory(new TempStream(), this.Password);

View on GitHub (pinned to f906a5f850)

Solutions

Set EngineSettings.Filename to a valid file path, ':memory:', or ':temp:'.
Or set EngineSettings.DataStream to a Stream (MemoryStream / custom) for in-memory or custom backing.
Validate settings before passing to the engine constructor.
If using a connection string, ensure the filename= key is present and non-empty.

Example fix

// before
var settings = new EngineSettings(); // no Filename, no DataStream
var db = new LiteEngine(settings); // throws

// after — file path
var db = new LiteDatabase("MyData.db");
// or in-memory
var db = new LiteDatabase(":memory:");
// or via settings
var settings = new EngineSettings { Filename = "MyData.db" };

Defensive patterns

Strategy: validation

Validate before calling

public LiteDatabase CreateDatabase(string filename, Stream dataStream = null, string password = null)
{
    if (string.IsNullOrWhiteSpace(filename) && dataStream == null)
        throw new ArgumentException("Either filename or DataStream must be provided.");
    var cs = $"Filename={filename};Password={password}";
    return new LiteDatabase(cs);
}

Type guard

static bool HasDataSource(EngineSettings s) =>
    !string.IsNullOrWhiteSpace(s.Filename) || s.DataStream != null;

Try / catch

try
{
    var db = new LiteDatabase(settings);
}
catch (ArgumentException ex) when (ex.Message.Contains("Filename or DataStream"))
{
    throw new ConfigurationException("Database connection is missing a Filename or DataStream.", ex);
}

Prevention

Always set Filename or DataStream before constructing the engine.
Validate connection strings at app startup with a health check.
Use ':memory:' or ':temp:' for ephemeral databases rather than leaving Filename null.
Add a DI registration test that opens the DB to catch missing config early.

When it happens

Trigger: Constructing an EngineSettings (or LiteDatabase with a connection string) where both Filename and DataStream are left null/empty. Happens when building settings programmatically and forgetting to assign a data source.

Common situations: Dependency injection registering LiteDatabase with a blank connection string; deserializing settings from JSON where Filename is missing; copy-paste from a sample that used DataStream when the app intended a file path.

Related errors

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