{
  "id": 10260284,
  "title": "MongoDB's 16MB document limit: how to find the doc that kills your agent run",
  "url": "https://urgent.news/2026/09/27/mongodbs-16mb-document-limit-how-to-find-the-doc-that-kills-your",
  "topic": "world",
  "section": "World",
  "published": "2026-09-27T17:15:01.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/milkyway008/mongodbs-16mb-document-limit-how-to-find-the-doc-that-kills-your-agent-run-2k68"
  },
  "original_language": "en",
  "account": "MongoDB imposes a strict 16MB limit on document size, which can cause issues when attempting to store large amounts of data, such as conversation history in a single document. This limit is hard-coded and cannot be altered via server flags or storage-engine options. When a document exceeds this size, the write is rejected entirely, leaving no partial data in the collection.\n\nTo identify documents nearing this limit, you can use MongoDB's aggregation framework to sort and filter documents by their BSON size. This process will reveal the largest documents in the workflow_snapshots collection, helping you pinpoint which document is likely to exceed the 16MB threshold and cause issues.\n\nThe root cause of this issue often lies in the nature of the data being stored. Agent state accumulates over time, with each turn appending messages, tool results, and other data to a growing array. This continuous growth can quickly lead to documents surpassing the 16MB limit, particularly when dealing with large tool results like log files or HTML pages.\n\nTo mitigate this problem, consider structuring your data model to separate growing arrays from the main document. Instead of storing the entire conversation history within a single document, create separate collections for messages and tool results, with the snapshot document maintaining a reference to these collections. This approach allows you to cap the size of the main document while still retaining access to the necessary data.\n\nAdditionally, consider using tools like GridFS for storing large files, as it splits files into chunks of 255KB each, effectively bypassing the 16MB limit. Another solution is to implement retention policies using TTL indexes to automatically delete old data, while being cautious as TTL indexes only apply to single-field expiration.\n\nWhile some proposed solutions, such as raising the limit or using capped collections, are not viable due to MongoDB's hard-coded limit or the nature of capped collections as append-only logs, the bucket pattern is an effective data-modeling strategy for managing time-sliced histories. However, be aware that the documentation surrounding this pattern has recently changed, and some resources may no longer be accessible.",
  "summary": "One of the agents I look after keeps its state in MongoDB, and a few weeks back it started doing the thing I dislike most: nothing. No stack trace, no failed HTTP call to point at. The run just sat there while the UI kept spinning. There was an error, all right. It wasn't in the app, it was in the database. A Mastra user hit the same wall in issue #21412. Long DurableAgent runs, MongoDB storage,…",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}