litedb-org/LiteDB · error · ArgumentException

Vector index operations require LiteDB's default collection

Error message

Vector index operations require LiteDB's default collection implementation.

What it means

Thrown by Unwrap in LiteCollectionVectorExtensions when the ILiteCollection<T> instance is not the concrete LiteCollection<T>. Vector index APIs rely on internal engine hooks only present on the default implementation, so a custom or wrapper collection cannot be used.

Source

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

        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. Operate on the raw LiteCollection<T> obtained from LiteDatabase.GetCollection<T> rather than a wrapper.
2. Expose the inner LiteCollection<T> from any decorator before invoking vector extension methods.
3. Adjust mocks/stubs to return or wrap a real LiteCollection<T> instance.

Example fix

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

// after
var raw = wrapped as LiteCollection<MyDoc> ?? inner;
raw.EnsureVectorIndex(x => x.Embedding, opts);

if (collection is not LiteCollection<MyDoc> raw)
    throw new InvalidOperationException("Vector operations require the default LiteCollection<T>.");
raw.EnsureVectorIndex(x => x.Embedding, opts);

static bool IsDefaultCollection<T>(ILiteCollection<T> c) => c is LiteCollection<T>;

When it happens

Trigger: Passing a decorated/proxy ILiteCollection<T> (e.g., a logging wrapper, a mock that implements the interface but does not subclass LiteCollection<T>) to EnsureVectorIndex or the vector EnsureIndex overload.

Common situations: Wrapping collections with decorators for auditing/caching; unit tests with hand-rolled stubs implementing ILiteCollection<T>; third-party LiteDB adapters that provide their own collection type.

Related errors

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

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