{"record":{"id":"d4a64324546d902f","repo":"litedb-org/LiteDB","slug":"the-type-bsonrefid-t-can-only-be-used-in-litedb-l","errorCode":null,"errorMessage":"The type BsonRefId<T> can only be used in LiteDB LINQ expressions.","messagePattern":"The type BsonRefId<T> can only be used in LiteDB LINQ expressions\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"LiteDB/Client/Mapper/BsonRefId.cs","lineNumber":31,"sourceCode":"///     {\n///       Id = x.Id,\n///       Bref = new BsonRefId&lt;B&gt;(100),\n///     },\n///     x => x.Id == 11);\n/// </code></example>\npublic sealed class BsonRefId<T>\n{\n    /// <summary>\n    /// Assigns the ID of the referenced entity of type <typeparamref name=\"T\"/>.\n    /// </summary>\n    /// <param name=\"id\">The ID to assign.</param>\n    public BsonRefId(BsonValue id)\n    {\n    }\n\n    public static implicit operator T(BsonRefId<T> _)\n    {\n        throw new NotSupportedException(\"The type BsonRefId<T> can only be used in LiteDB LINQ expressions.\");\n    }\n}\n","sourceCodeStart":13,"sourceCodeEnd":34,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Mapper/BsonRefId.cs#L13-L34","documentation":"Thrown by the implicit conversion operator BsonRefId<T> -> T. BsonRefId<T> is a marker type used only inside LiteDB LINQ expression trees (e.g. UpdateMany projections) to assign a DbRef id without loading the referenced entity. The implicit operator exists to satisfy the compiler but, if actually invoked at runtime, means the expression was not captured into a tree and processed by LiteDB's visitor.","triggerScenarios":"Using new BsonRefId<B>(id) in code that is NOT a LINQ expression tree LiteDB interprets, e.g. assigning it directly to a property of type B, or constructing a projection that gets compiled and executed rather than translated. Materializing a query whose Select yields a BsonRefId and then implicitly converting also triggers it.","commonSituations":"Copy-pasting the UpdateMany example into a regular method body instead of an expression lambda, or trying to read back a BsonRefId-typed value into a concrete entity property at runtime.","solutions":["Use BsonRefId<T> only inside expression lambdas passed to LiteDB methods like UpdateMany.","Ensure the lambda is typed as Expression<Func<T,T>> so it is captured as a tree, not compiled.","To assign a reference id directly, set the navigation property to a real entity or update the foreign-key field by name instead."],"exampleFix":"// before\nvar a = new A { Bref = new BsonRefId<B>(100) }; // runs the implicit operator -> throws\n\n// after\ndb.GetCollection<A>().UpdateMany(\n    x => new A { Id = x.Id, Bref = new BsonRefId<B>(100) }, // captured as Expression<Func<A,A>>\n    x => x.Id == 11);","handlingStrategy":"validation","validationCode":"// Only use BsonRefId inside an Expression<Func<T,T>> passed to LiteDB.\n// Do not assign new BsonRefId<T>(id) to a property of type T outside an expression tree.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep BsonRefId usage strictly inside UpdateMany/Update expression lambdas.","To set a reference id directly, update the foreign-key field by name instead.","Ensure the lambda is captured as an expression tree, not compiled and executed."],"tags":["mapper","dbref","linq","expression-tree","not-supported"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}