{"record":{"id":"20d8f60e83ff1d66","repo":"litedb-org/LiteDB","slug":"vector-index-operations-require-litedb-s-default-c","errorCode":null,"errorMessage":"Vector index operations require LiteDB's default collection implementation.","messagePattern":"Vector index operations require LiteDB's default collection implementation\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"LiteDB/Client/Vector/LiteCollectionVectorExtensions.cs","lineNumber":43,"sourceCode":"\n        public static bool EnsureIndex<T, K>(this ILiteCollection<T> collection, string name, Expression<Func<T, K>> keySelector, VectorIndexOptions options)\n        {\n            return Unwrap(collection).EnsureVectorIndex(name, keySelector, options);\n        }\n\n        private static LiteCollection<T> Unwrap<T>(ILiteCollection<T> collection)\n        {\n            if (collection is null)\n            {\n                throw new ArgumentNullException(nameof(collection));\n            }\n\n            if (collection is LiteCollection<T> concrete)\n            {\n                return concrete;\n            }\n\n            throw new ArgumentException(\"Vector index operations require LiteDB's default collection implementation.\", nameof(collection));\n        }\n    }\n}\n","sourceCodeStart":25,"sourceCodeEnd":47,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Vector/LiteCollectionVectorExtensions.cs#L25-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Operate on the raw LiteCollection<T> obtained from LiteDatabase.GetCollection<T> rather than a wrapper.","Expose the inner LiteCollection<T> from any decorator before invoking vector extension methods.","Adjust mocks/stubs to return or wrap a real LiteCollection<T> instance."],"exampleFix":"// before\nwrapped.EnsureVectorIndex(x => x.Embedding, opts);\n\n// after\nvar raw = wrapped as LiteCollection<MyDoc> ?? inner;\nraw.EnsureVectorIndex(x => x.Embedding, opts);","handlingStrategy":"type-guard","validationCode":"if (collection is not LiteCollection<MyDoc> raw)\n    throw new InvalidOperationException(\"Vector operations require the default LiteCollection<T>.\");\nraw.EnsureVectorIndex(x => x.Embedding, opts);","typeGuard":"static bool IsDefaultCollection<T>(ILiteCollection<T> c) => c is LiteCollection<T>;","tryCatchPattern":null,"preventionTips":["Operate on the raw LiteCollection<T> from GetCollection rather than wrappers.","Expose inner collection references from decorators for vector operations.","Configure mocks/stubs to wrap a real LiteCollection<T>."],"tags":["argument-validation","vector","type-check","collection","wrapper"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}