Jump to Section
Type vs. size of popular files uploaded in Umbraco
A large file is a relative term, depending on the specific project and type of file. Besides, the average file size is different in a regular website, where editors mostly upload images, than in a portal designed for a publisher, which would like to share more specific media files.
Probably, we can assume that the need to upload images is a must-have functionality in most Umbraco projects. Based on observations, a regular image will be smaller than 2 MB. Therefore, an image of about 10 MB can definitely be considered a large file.
Another popular media files are videos. It could be a short featured video or a bit longer, such as a showcase, tutorial, or training. Let's put aside movies, because it's a different story, and we don't want to cover all scenarios, including platforms like VOD. Let's assume that the average size of a video file is around 100 MB. However, a large video is typically measured in GB, ranging from 1 GB to 4 GB, which can hold approximately 40 minutes of HD video (1080p).
It's worth mentioning that PDF files are also among the most popular. Of course, the size of the PDF file depends on the content. Files containing mostly text and some images are considered small files, and they don't cause any problems. A PDF file that contains scanned documents will definitely be larger. However, a file containing 100 high-resolution scanned pages might reach 20 MB. It means that a 100 MB PDF file can definitely be considered a huge one.
In summary, when we refer to large files uploaded in Umbraco, we are most likely talking about video files.
Best video format for web projects
An MP4 video, compressed with the H.264 codec, is the most popular and widely supported video format for the web, offering a perfect balance between high video quality and relatively small file sizes. Of course, the WebM format can also be considered, which provides even smaller files, but it seems it's still not as popular as the MP4.
Universal Compatibility
MP4 is supported across most digital devices, browsers, and platforms, making it ideal for web streaming.
Efficient Compression
The H.264 codec provides excellent compression, resulting in smaller file sizes while maintaining high video quality.
High Quality
Despite its efficiency, MP4 delivers crisp, sharp video, ensuring a good viewing experience.
Versatile
It can store video, audio, text, and subtitles, making it a comprehensive format for web content.
Uploading large files in Umbraco
In our opinion, each Umbraco project should be configured accordingly to meet business requirements regarding file uploads. Otherwise, editors will encounter a problem while uploading files in the Media section sooner or later.
Unfortunately, in some corner cases, even if Umbraco is adequately configured, unexpected issues may arise. However, we aim to help resolve them by describing the most common scenarios.
First things first, so we recommend checking the Umbraco CMS documentation to determine the necessary configuration steps to achieve the expected results.
Setting the configuration
As you can see below, the documentation indicates that Umbraco doesn't limit the upload file size.
By default, Umbraco does not restrict upload size. The limits are controlled by the hosting platform.
However, you need to keep in mind that the Umbraco:CMS:Runtime:MaxRequestLength option takes effect in the back office UI, so it affects the system's functionality.
The Backoffice will use this value to help guide the users.
Please note that once Umbraco is hosted on Kestrel, you don't need to worry about other options. Otherwise, a specific configuration has to be set on the hosting platform. This configuration is primarily related to the size/length restrictions of data that will be sent to the application hosted on a specific platform.
Documentation inconsistency
Documentation indicates that you need to change the MaxRequestLength option to upload files larger than 28.6MB. Unfortunately, as an Umbraco editor, you will not receive any warning in the back office once hosted on Kestrel.
Moreover, in the documentation, we can see 28.6MB, but it seems to be 50MB, as you can see in the line of code:
In our opinion it's rather an issue related to the source code not documentation, because once the Umbraco:CMS:Runtime:MaxRequestLength is not set, the MaxRequestBodySize should not be modified to 50 MB.
Besides, the default value for IIS is 28.6 MB as you can see here:
Limitations on a local environment
Even if the CMS is hosted on Kestrel, Umbraco developers need to keep in mind that, when developing a website locally, they are typically running Umbraco on IIS Express or IIS in most cases.
Therefore, an appropriate configuration must be stored in the web.config file, so that IIS can rely on it.
<?xml version="1.0"?>
<configuration>
<system.webServer>
<security>
<requestFiltering>
<!-- 1 MB in bytes -->
<requestLimits maxAllowedContentLength="1048576" />
</requestFiltering>
</security>
</system.webServer>
</configuration>It's worth mentioning that during the calculation of the expected file size limit, we need to keep in mind two technical things:
- Correct convention for MB - megabyte (not megabit), so for 2 MB, it should be 2097152, not 2000000, as suggested in the documentation. Basically, it should be calculated this way: 2 * 1024 * 1024 B = 2 097 152 B, because we are referring to the size of binary data in the memory, and it's usually represented in MiB (mebibyte - the unambiguous binary unit).
- Total size of request, which is not only the size of the file, but also other items that will be sent together with the file, like HTTP headers.
Most common issues during file uploading
Configuring the file size limit for uploading is a straightforward process, and everything should work as expected. Unfortunately, based on our experience, Umbraco editors may encounter some issues, which we will attempt to explain and help resolve. Let's focus on the obvious and most popular cases, which are related to an inappropriate configuration.
Max file size is reached
If Umbraco editors see a red notification stating that "Max file size is ...KB" in the back office just before uploading is supposed to start, it means the file is larger than the limit configured by the MaxRequestLength option.
File too large to upload
If Umbraco editors can see that uploading starts successfully, but the "File too large to upload" error is being displayed once the progress bar reaches 100%, it means that the file is larger than the request limit configured in the hosting platform, e.g., IIS.
Specific issue during uploading a file in Umbraco
Based on our experience and testing, other issues can occur during the upload of a file, especially when uploading a large file.
Multipart body length limit exceeded
This particular issue can occur when the Umbraco:CMS:Runtime:MaxRequestLength is set to a value that should allow uploading files larger than 2 GB. The error message displayed for the editor can contain weird information about a negative limit.
We performed an investigation and confirmed that there is another bug in Umbraco, so we reported it here:
https://github.com/umbraco/Umbraco-CMS/issues/20343
Basically, it's caused by the integer overflow during multiplication while setting the MultipartBodyLengthLimit property of the FormOptions. in this line:
Once the Umbraco:CMS:Runtime:MaxRequestLength is set to 4 GB (4 194 304 KB), an error as below will be displayed:
Error: System.IO.InvalidDataException: Multipart body length limit 0 exceeded
Workaround before a fix is introduced in Umbraco
We have determined that we can utilize a temporary workaround until the bugfix is included in the upcoming Umbraco release.
Technically, we need to implement two classes as follows:
ConfigureFormOptionsProperly class
public class ConfigureFormOptionsProperly : IConfigureOptions<FormOptions>
{
private readonly IOptions<RuntimeSettings> _runtimeSettings;
public ConfigureFormOptionsProperly(IOptions<RuntimeSettings> runtimeSettings)
=> _runtimeSettings = runtimeSettings;
public void Configure(FormOptions options) =>
options.MultipartBodyLengthLimit = _runtimeSettings.Value.MaxRequestLength.HasValue
? _runtimeSettings.Value.MaxRequestLength.Value * 1024L
: long.MaxValue;
}ConfigureFormOptionsProperly class
public class ConfigureKestrelServerOptionsProperly : IConfigureOptions<KestrelServerOptions>
{
private readonly IOptions<RuntimeSettings> _runtimeSettings;
public ConfigureKestrelServerOptionsProperly(IOptions<RuntimeSettings> runtimeSettings) =>
_runtimeSettings = runtimeSettings;
public void Configure(KestrelServerOptions options) =>
options.Limits.MaxRequestBodySize = _runtimeSettings.Value.MaxRequestLength.HasValue
? _runtimeSettings.Value.MaxRequestLength.Value * 1024L
: 52428800;
}builder.CreateUmbracoBuilder()
.AddBackOffice()
.AddWebsite()
.AddDeliveryApi()
.AddComposers()
.Build();
builder.Services.ConfigureOptions<ConfigureKestrelServerOptionsProperly>();
builder.Services.ConfigureOptions<ConfigureFormOptionsProperly>();By the right place, I mean below the CreateUmbracoBuilder, because this extension is doing the same through another AddUmbraco extension, which you can confirm in this line of code:
Issue related to the specific file system provider
In some specific Umbraco projects, we have encountered an issue with uploading files larger than 2GB.
The stream was too long error
This error is presented for editors as the Error: An unknown error occurred caption in the back office. However, error details can be found in the Umbraco logs or the browser's console as below:
System.IO.IOException: Stream was too long.
at System.IO.MemoryStream.Write(Byte[] buffer, Int32 offset, Int32 count)
at System.IO.Stream.CopyTo(Stream destination, Int32 bufferSize)
at Our.Umbraco.StorageProviders.AWSS3.IO.AWSS3FileSystem.AddFile(String path, Stream stream, Boolean overrideIfExists)
at Our.Umbraco.StorageProviders.AWSS3.IO.AWSS3FileSystem.AddFile(String path, Stream stream)
at Umbraco.Cms.Core.IO.ShadowWrapper.AddFile(String path, Stream stream)
at Umbraco.Cms.Core.IO.MediaFileManager.StoreFile(IContentBase content, IPropertyType propertyType, String filename, Stream filestream, String oldpath)
at Umbraco.Extensions.ContentExtensions.SetUploadFile(IContentBase content, MediaFileManager mediaFileManager, MediaUrlGeneratorCollection mediaUrlGenerators, IContentTypeBaseServiceProvider contentTypeBaseServiceProvider, String propertyTypeAlias, String filename, Stream filestream, String culture, String segment)
at Umbraco.Extensions.ContentExtensions.SetValue(IContentBase content, MediaFileManager mediaFileManager, MediaUrlGeneratorCollection mediaUrlGenerators, IShortStringHelper shortStringHelper, IContentTypeBaseServiceProvider contentTypeBaseServiceProvider, String propertyTypeAlias, String filename, Stream filestream, String culture, String segment)
at Umbraco.Cms.Web.BackOffice.Controllers.MediaController.PostAddFile(String path, String currentFolder, String contentTypeAlias, List`1 file)
at Umbraco.Cms.Web.BackOffice.Controllers.MediaController.PostAddFile(String path, String currentFolder, String contentTypeAlias, List`1 file)
at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.TaskOfIActionResultExecutor.Execute(ActionContext actionContext, IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)Moreover, as an Umbraco editor, you will be able to see the possibly unhandled rejection error in the browser's console.
During our investigation, we have confirmed that this specific error is caused by the MemoryStream used in the AWSS3FileSystem implemented in the popular Our.Umbraco.StorageProviders.AWSS3 package.
Direct link to the line causing the issue:
We have determined that this issue is due to a well-known limitation of the MemoryStream class.
According to the source code of the MemoryStream class, you will not be able to store more than 2 GB of data into one instance of this class. The reason for this is that the maximum length of the stream is set to Int32.MaxValue.
Of course, we had been considering the implementation of our own AWSS3FileSystemProvider and creating another Umbraco package, but we have decided to raise an issue on GitHub:
https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3/issues/29
This way, we would like to help improve the existing package with minimal effort.
Anyway, before raising a new ticket in the GitHub issue tracker, we have decided to prepare a Custom File System Provider based on the existing AWSS3FileSystemProvider and prove that it can be resolved quickly.
Of course, you can do the same and take advantage of it until the issue is fixed and a new version is released.
The root cause can be found in the AddFile method of the AWSS3FileSystem implementation as follows:
public void AddFile(string path, Stream stream, bool overrideIfExists)
{
if (!overrideIfExists && FileExists(path))
{
throw new InvalidOperationException($"A file at path '{path}' already exists");
}
using (var memoryStream = new MemoryStream())
{
stream.CopyTo(memoryStream);
AddFileFromStream(path, memoryStream);
}
}The implementation that resolves the issue looks as below:
public void AddFile(string path, Stream stream, bool overrideIfExists)
{
if (!overrideIfExists && FileExists(path))
{
throw new InvalidOperationException($"A file at path '{path}' already exists");
}
AddFileFromStream(path, memoryStream);
}Direct link to the existing implementation which causes the error:
It's worth mentioning that the OpenFile method, which implements the IAWSS3FileSystem interface, also relies on the MemoryStream, as you can confirm here:
This means that we can expect similar issues during other operations involving large files, so it's recommended to address this issue as well.
Uploading files to the Azure Blob Storage
We were interested in whether the same issue occurs in the other well-known File System Provider designed for the Azure Blob Storage.
Therefore, we have decided to perform additional tests and confirmed that the issue doesn't occur in Umbraco.StorageProviders.AzureBlob.
It means you don't need to worry about similar issues once your Umbraco stores media files in the Azure Blob Storage instead of the AWS S3 bucket.
Other issues with uploading
Unfortunately, there is a risk that other issues may arise during the upload of large files. During the investigation, we recommend considering whether the progress bar indicating the uploading process is being completed or not.
If you have gone through all the problems described in this article but are still struggling with uploading large files, it probably means that the application or infrastructure is unable to handle such a request, or it's blocked by a WAF (Web Application Firewall).
So we recommend contacting your DevOps team to ensure the environment is configured as expected to handle uploading requests.
Conclusion
Configure limits at the right layer (Kestrel/IIS/cloud) and set MaxRequestLength for Backoffice guidance.
Watch for edge cases such as integer overflows in multipart limits and MemoryStream usage in third‑party providers.
For AWS S3, apply the stream‑through fix. For Azure Blob, the official provider is unaffected.
With these adjustments, editors can reliably upload even very large videos while maintaining platform stability.