litedb-org/LiteDB · error · LiteException

0

0

Error message

Document size exceed {0} limit

What it means

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.

Source

Thrown at LiteDB/Engine/Services/DataService.cs:35

            DataBlock.DATA_BLOCK_FIXED_SIZE; // [6 bytes];

        private readonly Snapshot _snapshot;
        private readonly uint _maxItemsCount;

        public DataService(Snapshot snapshot, uint maxItemsCount)
        {
            _snapshot = snapshot;
            _maxItemsCount = maxItemsCount;
        }

        /// <summary>
        /// Insert BsonDocument into new data pages
        /// </summary>
        public PageAddress Insert(BsonDocument doc)
        {
            var bytesLeft = doc.GetBytesCount(true);

            if (bytesLeft > MAX_DOCUMENT_SIZE) throw new LiteException(0, "Document size exceed {0} limit", MAX_DOCUMENT_SIZE);

            var firstBlock = PageAddress.Empty;

            IEnumerable<BufferSlice> source()
            {
                var blockIndex = 0;
                DataBlock lastBlock = null;

                while (bytesLeft > 0)
                {
                    var bytesToCopy = Math.Min(bytesLeft, MAX_DATA_BYTES_PER_PAGE);
                    var dataPage = _snapshot.GetFreeDataPage(bytesToCopy + DataBlock.DATA_BLOCK_FIXED_SIZE);
                    var dataBlock = dataPage.InsertBlock(bytesToCopy, blockIndex++ > 0);

                    if (lastBlock != null)
                    {
                        lastBlock.SetNextBlock(dataBlock.Position);
                    }

View on GitHub (pinned to f906a5f850)

Solutions

1. 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.
2. Split the document into multiple smaller related documents linked by _id.
3. Compress large string/binary fields before insertion.
4. If inserting a batch, verify each document's GetBytesCount(true) is under the limit before sending.

Example fix

// before — huge embedded blob
var doc = new BsonDocument { ["_id"] = 1, ["data"] = hugeByteArray };
col.Insert(doc); // throws if > ~16 MB

// after — store blob via LiteStorage, keep reference
var fileId = db.FileStorage.Upload("$files/data_1", stream);
var doc = new BsonDocument { ["_id"] = 1, ["fileId"] = fileId.AsString };
col.Insert(doc);

const int MAX_DOC_BYTES = 2047 * 8150; // 16,683,050

public void InsertSafely(ILiteCollection<BsonDocument> col, BsonDocument doc)
{
    var size = doc.GetBytesCount(true);
    if (size > MAX_DOC_BYTES)
        throw new InvalidOperationException($"Document is {size} bytes; max is {MAX_DOC_BYTES}. Move large payloads to LiteStorage.");
    col.Insert(doc);
}

static bool IsWithinSizeLimit(BsonDocument doc) =>
    doc.GetBytesCount(true) <= 2047 * 8150;

try
{
    col.Insert(doc);
}
catch (LiteException ex) when (ex.Message.Contains("Document size exceed"))
{
    // Offload the large blob to LiteStorage and store a reference instead.
    throw new InvalidOperationException("Document exceeds the ~16 MB BSON limit. Use LiteStorage for large blobs.", ex);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 0
• 0
• 0
• Extend expression must return a document
• 0

AI-assisted analysis of litedb-org/LiteDB@f906a5f850 (2026-08-13). Data as JSON: /api/errors/75e23ae055b2064f. Report an issue: GitHub.