litedb-org/LiteDB · error · ArgumentNullException

Value cannot be null. (Parameter 'collection')

Error message

Value cannot be null. (Parameter 'collection')

What it means

Thrown by the private Unwrap helper in LiteCollectionVectorExtensions when the collection passed to a vector-index extension method is null. The extension methods (EnsureVectorIndex/EnsureIndex overloads) delegate to the concrete LiteCollection<T>, so a null receiver has no real target to operate on.

Source

Thrown at LiteDB/Client/Vector/LiteCollectionVectorExtensions.cs:35

        {
            return Unwrap(collection).EnsureVectorIndex(expression, options);
        }

        public static bool EnsureIndex<T, K>(this ILiteCollection<T> collection, Expression<Func<T, K>> keySelector, VectorIndexOptions options)
        {
            return Unwrap(collection).EnsureVectorIndex(keySelector, options);
        }

        public static bool EnsureIndex<T, K>(this ILiteCollection<T> collection, string name, Expression<Func<T, K>> keySelector, VectorIndexOptions options)
        {
            return Unwrap(collection).EnsureVectorIndex(name, keySelector, options);
        }

        private static LiteCollection<T> Unwrap<T>(ILiteCollection<T> collection)
        {
            if (collection is null)
            {
                throw new ArgumentNullException(nameof(collection));
            }

            if (collection is LiteCollection<T> concrete)
            {
                return concrete;
            }

            throw new ArgumentException("Vector index operations require LiteDB's default collection implementation.", nameof(collection));
        }
    }
}

View on GitHub (pinned to f906a5f850)

Solutions

1. Verify the collection reference is non-null before calling any vector extension; check the LiteDatabase is not disposed.
2. Ensure the collection is obtained from a live LiteDatabase instance via db.GetCollection<T>(name).
3. Fix DI/mock setups so the collection is always resolved to a real instance.

Example fix

// before
collection.EnsureVectorIndex(x => x.Embedding, opts);

// after
if (collection is null)
    throw new InvalidOperationException("Collection was not resolved from the database.");
collection.EnsureVectorIndex(x => x.Embedding, opts);

if (collection is null)
    throw new InvalidOperationException("Collection is not initialized.");
collection.EnsureVectorIndex(x => x.Embedding, opts);

static bool IsLiveCollection<T>(ILiteCollection<T> c) => c is not null;

When it happens

Trigger: Calling collection.EnsureVectorIndex(...) on a null ILiteCollection<T>; retrieving a collection from a disposed database; a DI container injecting null for the collection.

Common situations: Using a collection obtained via db.GetCollection<T>(name) after the LiteDatabase was disposed; mock frameworks returning default (null) from a setup that was never configured; conditional collection access where the variable was never assigned.

Related errors

• Value cannot be null. (Parameter 'source')
• Value cannot be null. (Parameter 'repository')
• Vector index operations require LiteDB's default collection
• Value cannot be null. (Parameter 'collection')
• Vector operations require LiteDB's default queryable impleme

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