When a file exceeds the Salesforce file size limit, the upload fails and Salesforce returns an error message. The default maximum file size for Salesforce Files is 2 GB, but practical limits vary depending on how you’re uploading and which Salesforce feature you’re using. Understanding where these limits apply and why uploads fail helps you find the right workaround before it slows your team down.
Salesforce enforces different file size limits depending on the feature you’re using. For Salesforce Files (the modern standard), the maximum file size is 2 GB per file. For older Salesforce Attachments, the limit drops to 25 MB. API-based uploads have their own constraints, and certain file types may be subject to additional restrictions set by your org’s administrator.
Here’s a quick breakdown of the most common limits you’ll run into:
Beyond individual file limits, your org also has a total storage cap. Salesforce allocates a set amount of file storage per license type, and once your org hits that ceiling, no new files can be saved regardless of individual file size.
When you try to upload a file that exceeds the applicable Salesforce size limit, the upload fails immediately. Salesforce blocks the file before it completes and displays an error message indicating the file is too large. No partial file is saved, and the record you were trying to attach it to remains unchanged.
The exact error message depends on which upload method you’re using. Through the standard UI, you’ll typically see a notification directly in the browser. Through the API, the response will include an error code referencing the file size constraint. Either way, the result is the same: the file doesn’t go through, and your workflow stalls until you find an alternative.
This is particularly disruptive in fast-moving teams. If a project manager in a real estate firm is trying to attach a large architectural drawing or a signed contract package to a Salesforce record, a failed upload doesn’t just waste a few seconds. It breaks the flow, forces a workaround, and often means the document ends up stored somewhere outside Salesforce entirely, which creates exactly the kind of scattered file situation that slows teams down.
Large files fail to upload in Salesforce for several reasons beyond just hitting the size ceiling. The most common causes are browser timeouts during slow uploads, unstable network connections that interrupt the transfer, and API request limits that prevent single-call uploads of files above a certain size. Even files technically under the 2 GB limit can fail if the upload conditions aren’t right.
A few specific culprits worth checking:
The most practical workarounds for Salesforce file size restrictions are compressing files before upload, splitting large files into smaller parts, using chunked API uploads for programmatic transfers, or connecting Salesforce to external storage where the file actually lives while keeping a linked reference inside Salesforce.
For everyday users who don’t want to get into technical configurations, compression is the fastest fix. Tools built into most operating systems can reduce file sizes significantly, especially for document types like PDFs or presentation files. For video or high-resolution media assets, compression may not be enough, and external storage becomes the more realistic path.
For teams handling bulk file uploads regularly, the better long-term solution is to rethink where large files live. Storing a reference or link inside Salesforce, while the actual file sits in a connected storage environment, keeps your Salesforce org lean and your team’s access seamless.
Salesforce Files and Salesforce Attachments are two different systems for storing documents in Salesforce. Salesforce Files is the modern, recommended approach with a 2 GB per-file limit, sharing and collaboration features, and integration with Salesforce’s content library. Salesforce Attachments is the older system, limited to 25 MB per file, with no sharing capabilities and no connection to the content library.
Salesforce has been steering users away from Attachments for years. The Attachments object is considered legacy, and Salesforce no longer invests in developing it. If your team is still using Attachments, you’re working with a more restricted system in terms of both file size and functionality.
The practical difference matters most when you’re dealing with large files. A 30 MB contract document will fail on Attachments but upload fine through Salesforce Files. If your team runs into frequent upload errors, one of the first things to check is whether you’re working with the Files system or accidentally using the older Attachments object.
You should consider external document storage when your files are consistently large, when your team collaborates on documents in real time, or when your Salesforce org is approaching its storage limit. External storage keeps Salesforce fast and lean while still letting your team access documents directly from Salesforce records through linked references.
External storage makes the most sense in these scenarios:
The key is that “external storage” doesn’t have to mean “disconnected from Salesforce.” A well-integrated solution keeps documents accessible from Salesforce records without forcing users to switch platforms or hunt through separate systems.
Managing Salesforce storage proactively means regularly auditing what’s stored, removing duplicate or outdated files, compressing large documents where possible, and setting clear policies for what belongs in Salesforce versus external storage. Waiting until the org is full creates an emergency cleanup situation that disrupts everyone.
A few practical habits that help:
Consistent storage hygiene is easier to maintain than a reactive cleanup. Building it into a monthly or quarterly routine prevents the slow creep toward a full org that eventually blocks uploads entirely.
We built Cartularius to solve exactly the kind of friction described throughout this article. Whether your team is hitting upload limits, dealing with scattered files, or struggling to keep Salesforce storage under control, Cartularius gives you a smarter way to manage documents without leaving Salesforce.
Here’s what that looks like in practice:
If your team is ready to stop fighting Salesforce storage limits and start treating documents as a real operational asset, take a look at what Cartularius can do for you.
Install Cartularius now and experience the best Salesforce document management solution and enjoy clean and structured data and optimized processes, risk-free for 30 days.