{"record":{"id":"6d99acbf2eb0ff14","repo":"litedb-org/LiteDB","slug":"bsonrefid-t-requires-a-dbref-collection-name-mem","errorCode":null,"errorMessage":"BsonRefId<T> requires a DbRef collection name. Member '{memberMapper.MemberName}' is missing it (use [BsonRef] or Entity<T>().DbRef(...)).","messagePattern":"BsonRefId<T> requires a DbRef collection name\\. Member '(.+?)' is missing it \\(use \\[BsonRef\\] or Entity<T>\\(\\)\\.DbRef\\(\\.\\.\\.\\)\\)\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"LiteDB/Client/Mapper/Linq/LinqExpressionVisitor.cs","lineNumber":755,"sourceCode":"            }\n\n            return value;\n        }\n\n        /// <summary>\n        /// Tries to visit `new BsonRefId&lt;T&gt;(id)` within a member init expression.\n        /// This is only resolved for properties marked as DbRef.\n        /// </summary>\n        private bool TryVisitDbRefIdExpression(Expression node, MemberMapper memberMapper, bool isInList = false)\n        {\n            if (!memberMapper.IsDbRef)\n            {\n                return false;\n            }\n\n            if (string.IsNullOrWhiteSpace(memberMapper.DbRefCollectionName))\n            {\n                throw new NotSupportedException($\"BsonRefId<T> requires a DbRef collection name. Member '{memberMapper.MemberName}' is missing it (use [BsonRef] or Entity<T>().DbRef(...)).\");\n            }\n\n            switch (node)\n            {\n                // Implicit convert from BsonRefId<T> to T\n                case UnaryExpression { NodeType: ExpressionType.Convert, Method: { Name: \"op_Implicit\" }, Operand: var operand }:\n                    return TryVisitDbRefIdExpression(operand, memberMapper, isInList);\n\n                // The actual new BsonRefId<T>\n                case NewExpression { Members: null, Type.IsConstructedGenericType: true } expr\n                    when expr.Type.GetGenericTypeDefinition() == typeof(BsonRefId<>):\n\n                    var typeOfRef = expr.Type.GetGenericArguments()[0];\n\n                    // Type of ref must be assignable to property or if within a list assignable to the list type.\n                    if (memberMapper.DataType.IsAssignableFrom(typeOfRef) || isInList && memberMapper.UnderlyingType.IsAssignableFrom(typeOfRef))\n                    {\n                        ResolveDbRefId(expr, memberMapper);","sourceCodeStart":737,"sourceCodeEnd":773,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Mapper/Linq/LinqExpressionVisitor.cs#L737-L773","documentation":"Thrown when a LINQ expression assigns a BsonRefId<T> to a property that is registered as a DbRef but whose target collection name is null or empty. LiteDB needs the collection name to emit the {$id, $ref} reference document, so it refuses to translate the expression without one. The DbRefCollectionName is normally populated by [BsonRef(\"collection\")] or Entity<T>().DbRef(x => x.Prop, \"collection\").","triggerScenarios":"A DbRef member was declared with [BsonRef] (parameterless) or via DbRef(...) without a collection argument, and the mapper could not infer the name from the type. A LINQ update/insert expression then uses new BsonRefId<T>(id) on that member, entering TryVisitDbRefIdExpression where IsDbRef is true but DbRefCollectionName is blank.","commonSituations":"Using the parameterless [BsonRef] attribute and expecting auto-inference from the type name when it doesn't match the convention. Migrating from an older LiteDB version where collection names were optional. Using a fluent mapper Entity<T>().DbRef(x => x.Prop) without the second string argument.","solutions":["Add an explicit collection name to the attribute: [BsonRef(\"myCollection\")] on the property.","Use the fluent API with a name: db.Mapper.Entity<T>().DbRef(x => x.Prop, \"myCollection\").","Ensure the referenced type's default collection name (type name lowercased) matches an actual collection in the database."],"exampleFix":"// before\npublic class Order\n{\n    [BsonRef]\n    public Customer Customer { get; set; }\n}\n// after\npublic class Order\n{\n    [BsonRef(\"customers\")]\n    public Customer Customer { get; set; }\n}","handlingStrategy":"validation","validationCode":"// Before building LINQ update expressions, verify DbRef members have a collection name\nvar mapper = db.Mapper;\nvar entity = mapper.GetEntityMapper<Order>();\nforeach (var member in entity.Members.Where(m => m.IsDbRef))\n{\n    if (string.IsNullOrWhiteSpace(member.DbRefCollectionName))\n        throw new InvalidOperationException(\n            $\"Member {member.MemberName} is a DbRef without a collection name. Add [BsonRef(\\\"name\\\")] or Entity<T>().DbRef(..., \\\"name\\\").\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    col.UpdateMany(x => new Order { Customer = new BsonRefId<Customer>(id) }, x => x.Id == orderId);\n}\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"DbRef collection name\"))\n{\n    // Fix the mapping: add [BsonRef(\"customers\")] to the property\n    throw;\n}","preventionTips":["Always specify the collection name in [BsonRef(\"collectionName\")] rather than relying on the parameterless overload.","Centralize entity mapping configuration in one place (e.g., a ConfigureMapper method) and review all DbRef declarations.","Write a startup test that loads the entity mapper and asserts every IsDbRef member has a non-empty DbRefCollectionName."],"tags":["linq","dbref","mapper","bsonrefid"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}