{"record":{"id":"3375e647741f9223","repo":"litedb-org/LiteDB","slug":"entity-initialization-failed","errorCode":"ENTITY_INITIALIZATION_FAILED","errorMessage":"Initialization timeout","messagePattern":"Initialization timeout","errorType":"exception","errorClass":"LiteException","httpStatus":null,"severity":"error","filePath":"LiteDB/Client/Mapper/EntityMapper.cs","lineNumber":67,"sourceCode":"        {\n            return this.Members.FirstOrDefault(x => x.MemberName == expr.GetPath());\n        }\n\n        public void WaitForInitialization()\n        {\n            if\n            (\n                _initializationToken == default\n                || _initializationToken == CancellationToken.None\n                || _initializationToken.IsCancellationRequested\n            )\n            {\n                return;\n            }\n\n            if (!_initializationToken.WaitHandle.WaitOne(TimeSpan.FromSeconds(5)))\n            {\n                throw new LiteException(LiteException.ENTITY_INITIALIZATION_FAILED, \"Initialization timeout\");\n            }\n        }\n    }\n}","sourceCodeStart":49,"sourceCodeEnd":71,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Client/Mapper/EntityMapper.cs#L49-L71","documentation":"Thrown by EntityMapper.WaitForInitialization when the CancellationToken WaitHandle is not signalled within 5 seconds. The token comes from GetEntityMapper, which creates a CancellationTokenSource, builds the EntityMapper via BuildEntityMapper, then cancels the token in its finally block. A timeout means BuildEntityMapper took longer than 5 seconds, indicating the entity build is stuck or extremely slow.","triggerScenarios":"Any code path that calls WaitForInitialization (EntityBuilder.GetMember, LinqExpressionVisitor.ResolveMember, or direct calls) while GetEntityMapper is still executing BuildEntityMapper for the same or a related type and that build has not completed within the 5-second window.","commonSituations":"A custom BsonMapper.ResolveMember callback that performs slow or blocking work (network, disk, heavy computation). A deeply recursive or circular entity graph that causes GetEntityMapper to call itself in a way that stalls. Heavy resource contention on first use under load without pre-warming the mapper. A deadlock between threads if a custom resolver callback re-enters the mapper on the same type from a different thread.","solutions":["Inspect custom ResolveMember, ResolveFieldName, ResolveCollectionName, and ResolveTypeName callbacks for slow or blocking operations and make them synchronous and fast.","Pre-warm the mapper at application startup by calling mapper.GetEntityMapper(typeof(T)) for each entity type before concurrent queries hit it.","Simplify complex or self-referencing entity graphs and break circular DbRef chains.","If using a custom BsonMapper subclass, ensure BuildEntityMapper/GetTypeMembers overrides do not call back into GetEntityMapper in a way that could deadlock."],"exampleFix":"// before -- custom resolver does slow work\nmapper.ResolveMember = (type, memberInfo, memberMapper) =>\n{\n    memberMapper.FieldName = LoadAliasFromDatabase(memberInfo.Name); // blocking I/O\n};\n\n// after -- cache aliases up front\nvar aliases = LoadAllAliases(); // at startup\nmapper.ResolveMember = (type, memberInfo, memberMapper) =>\n{\n    if (aliases.TryGetValue(memberInfo.Name, out var alias))\n        memberMapper.FieldName = alias;\n};","handlingStrategy":"validation","validationCode":"// Pre-warm all entity types at startup to avoid initialization under load\nforeach (var entityType in new[] { typeof(User), typeof(Order), typeof(Product) })\n{\n    mapper.GetEntityMapper(entityType);\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    mapper.GetEntityMapper(typeof(T));\n}\ncatch (LiteException ex) when (ex.ErrorCode == LiteException.ENTITY_INITIALIZATION_FAILED)\n{\n    logger.LogError(ex, \"Entity mapping initialization timed out for {Type}\", typeof(T).Name);\n    throw;\n}","preventionTips":["Keep BsonMapper.ResolveMember and related callbacks fast and non-blocking.","Pre-warm the mapper by calling GetEntityMapper for all entity types at application startup.","Avoid calling GetEntityMapper concurrently for interdependent types from multiple threads on first use.","Audit custom BsonMapper subclass overrides for re-entrant calls that could deadlock."],"tags":["mapper","initialization","timeout","threading"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}