{"record":{"id":"75e23ae055b2064f","repo":"litedb-org/LiteDB","slug":"0-75e23a","errorCode":"0","errorMessage":"Document size exceed {0} limit","messagePattern":"Document size exceed (.+?) limit","errorType":"exception","errorClass":"LiteException","httpStatus":null,"severity":"error","filePath":"LiteDB/Engine/Services/DataService.cs","lineNumber":35,"sourceCode":"            DataBlock.DATA_BLOCK_FIXED_SIZE; // [6 bytes];\n\n        private readonly Snapshot _snapshot;\n        private readonly uint _maxItemsCount;\n\n        public DataService(Snapshot snapshot, uint maxItemsCount)\n        {\n            _snapshot = snapshot;\n            _maxItemsCount = maxItemsCount;\n        }\n\n        /// <summary>\n        /// Insert BsonDocument into new data pages\n        /// </summary>\n        public PageAddress Insert(BsonDocument doc)\n        {\n            var bytesLeft = doc.GetBytesCount(true);\n\n            if (bytesLeft > MAX_DOCUMENT_SIZE) throw new LiteException(0, \"Document size exceed {0} limit\", MAX_DOCUMENT_SIZE);\n\n            var firstBlock = PageAddress.Empty;\n\n            IEnumerable<BufferSlice> source()\n            {\n                var blockIndex = 0;\n                DataBlock lastBlock = null;\n\n                while (bytesLeft > 0)\n                {\n                    var bytesToCopy = Math.Min(bytesLeft, MAX_DATA_BYTES_PER_PAGE);\n                    var dataPage = _snapshot.GetFreeDataPage(bytesToCopy + DataBlock.DATA_BLOCK_FIXED_SIZE);\n                    var dataBlock = dataPage.InsertBlock(bytesToCopy, blockIndex++ > 0);\n\n                    if (lastBlock != null)\n                    {\n                        lastBlock.SetNextBlock(dataBlock.Position);\n                    }","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Engine/Services/DataService.cs#L17-L53","documentation":"Thrown by DataService.Insert (and Update) when the serialized size of a BsonDocument exceeds MAX_DOCUMENT_SIZE (2047 * 8150 = 16,683,050 bytes, ~15.9 MB). LiteDB stores documents across a chain of data pages, each holding at most MAX_DATA_BYTES_PER_PAGE (8150) bytes; the 2047-page chain length is the hard cap, matching MongoDB's 16 MB BSON limit. The check uses doc.GetBytesCount(true) which includes the _id and all fields.","triggerScenarios":"Inserting or updating a document whose BSON serialization exceeds ~16.7 MB — typically due to a very large embedded array or binary blob. Also triggered on Update when a document grows past the limit.","commonSituations":"Embedding large file blobs, base64-encoded media, or huge arrays directly in a document instead of using GridFS/external storage; batch-inserting unwieldy JSON; accumulating audit/log arrays in a single growing document.","solutions":["Move large binary/array payloads out of the document — store files in LiteDB's file storage (LiteStorage) or an external blob store and keep only a reference.","Split the document into multiple smaller related documents linked by _id.","Compress large string/binary fields before insertion.","If inserting a batch, verify each document's GetBytesCount(true) is under the limit before sending."],"exampleFix":"// before — huge embedded blob\nvar doc = new BsonDocument { [\"_id\"] = 1, [\"data\"] = hugeByteArray };\ncol.Insert(doc); // throws if > ~16 MB\n\n// after — store blob via LiteStorage, keep reference\nvar fileId = db.FileStorage.Upload(\"$files/data_1\", stream);\nvar doc = new BsonDocument { [\"_id\"] = 1, [\"fileId\"] = fileId.AsString };\ncol.Insert(doc);","handlingStrategy":"validation","validationCode":"const int MAX_DOC_BYTES = 2047 * 8150; // 16,683,050\n\npublic void InsertSafely(ILiteCollection<BsonDocument> col, BsonDocument doc)\n{\n    var size = doc.GetBytesCount(true);\n    if (size > MAX_DOC_BYTES)\n        throw new InvalidOperationException($\"Document is {size} bytes; max is {MAX_DOC_BYTES}. Move large payloads to LiteStorage.\");\n    col.Insert(doc);\n}","typeGuard":"static bool IsWithinSizeLimit(BsonDocument doc) =>\n    doc.GetBytesCount(true) <= 2047 * 8150;","tryCatchPattern":"try\n{\n    col.Insert(doc);\n}\ncatch (LiteException ex) when (ex.Message.Contains(\"Document size exceed\"))\n{\n    // Offload the large blob to LiteStorage and store a reference instead.\n    throw new InvalidOperationException(\"Document exceeds the ~16 MB BSON limit. Use LiteStorage for large blobs.\", ex);\n}","preventionTips":["Store large blobs via LiteStorage, not embedded in documents.","Check doc.GetBytesCount(true) before inserting if payloads vary widely.","Split growing documents into multiple related documents.","Compress large string/binary fields before insertion."],"tags":["document-size","insert","schema-limit","litedb-engine"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}