The 25 MB Notes & Attachments limit: what breaks, and what to do instead

A document generator works perfectly for months. Then somebody adds a logo to a template, or a contract picks up an extra thirty pages of schedules, and the generation fails. The record shows nothing. The user tries again, and it fails again.

Almost every time, the cause is the same: the document is being filed into Notes & Attachments, and it has crossed 25 MB.

The failure nobody sees coming

What makes this limit unusually painful is not the number. It is when you meet it. Nothing warns you while you are building the template, because the template is small. Nothing warns you in testing, because test records have three line items rather than three hundred. The limit is discovered in production, by whoever generated the largest document anyone had tried so far.

And it fails at the end. The Salesforce query ran. The merge ran. The PDF was produced correctly. It is the very last step, writing the file to the record, that refuses - which is why the error, when you find it, so rarely says anything about size.

The document was never wrong. It was simply too large for the drawer somebody chose to keep it in.

Why 25 MB, and 25 MB of what

Salesforce has two places to keep a file against a record, and they are separate systems with separate histories.

• Notes & Attachments stores an Attachment record. This is the classic mechanism, and Salesforce caps a single attachment at 25 MB.
• Files stores a ContentVersion, surfaced as a ContentDocument. This is the modern mechanism, and its ceiling is measured in gigabytes rather than megabytes.

The 25 MB figure is not a setting, a per-org allocation or something support can raise. It is a property of the object. If your document is 26 MB, no amount of configuration will put it in Notes & Attachments.

The encoding tax

There is a second, quieter problem. Files do not travel to Salesforce as raw bytes when they go through the API - they are base64 encoded, and base64 is larger than what it encodes. Roughly four characters for every three bytes.

The practical effect is that a document comfortably under a stated limit can exceed it in transit. A 25 MB file becomes about 33 MB of encoded payload. Anything sizing the request against the original file is measuring the wrong number.

Rule of thumb. Multiply the real file size by about 1.35 to get what actually crosses the wire. If your ceiling is on the request rather than the file, that is the number that has to fit under it.

This is why an integration can behave differently for two documents that look near-identical in a file browser. One landed just under a threshold after encoding, and one did not.

What the two stores actually differ on

Size is the difference that breaks things, but it is not the only one worth knowing before you pick.

That last row is why Notes & Attachments has not simply disappeared. Plenty of orgs have years of automation, reports and habits built around the classic related list, and moving is a real project rather than a checkbox.

Choosing, and choosing early

The decision belongs at template level, not org level, because different documents have genuinely different needs. A one-page confirmation letter will never approach 25 MB. A signed construction contract with drawings attached will pass it without effort.

What matters is that the choice is made deliberately and stated visibly. The worst version of this is a default nobody chose, discovered eighteen months later by a failure.

A trap worth knowing. If a rule watches Notes & Attachments for documents to act on, and the generator writes documents larger than 25 MB, the rule does not error. It simply never fires, because the file it is waiting for can never appear. Silent, and extremely hard to diagnose from the outside.

Bundles are where this bites

Single documents rarely cross 25 MB. Merged ones do it routinely. Combine a cover letter, a master agreement, a fee schedule and an annexe or two, add a logo on every page and a scanned appendix, and the total climbs quickly.

Images are the usual culprit. A logo saved at print resolution and repeated across forty pages will do more damage than the text of the entire contract.

1. Check the size of your largest realistic bundle, not your typical one.
2. Look at image resolution in the template before you look at anything else.
3. If the answer is anywhere near 25 MB, choose Files and stop thinking about it.

What to do about it

The remedy is not complicated. It is simply easier to apply before the failure than after it.

• Default to Files unless a classic process genuinely requires otherwise.
• Set the store per template, so a small letter and a large contract are not forced into the same decision.
• Keep the signed copy with the original. If the generated document is in Files, the signed version should be too - a pair split across two stores is a support ticket waiting to happen.
• Surface the limit at the point of choice. A warning while somebody is picking a store costs nothing. The same information delivered as a production failure costs an afternoon.

How we handle it. Savvy DocGen sets the store per template, caps documents at 40 MB, and shows a warning the moment Notes & Attachments is selected - on the template and on any automation rule watching that store. It is a small piece of interface that exists entirely because this failure is so unpleasant to diagnose.

Read next