Always use File Chunking to Upload Files > 250 MB to SharePoint Online

This post is a contribution from Adam Burns, an engineer with the SharePoint Developer Support team

Some developers may have been confused by some of the information available on blogs (and even on MSDN) about the upper limit of file sizes that can be programmatically uploaded to SharePoint Online using the SharePoint REST API. The maximum file upload size in SharePoint Online follows the default limit that can be seen in Central Admin’s Web Application General Settings for SharePoint On-Premises:

Of course, in SharePoint Online you don’t have access to this setting.

Whether you use the /Add method…
https://msdn.microsoft.com/en-us/library/office/dn450841.aspx#bk_FileCollectionAdd

…or the /SaveBinaryStream method…
https://msdn.microsoft.com/en-us/library/office/dn450841.aspx#bk_FileSaveBinaryStream

…in SharePoint Online, you will be limited to the 250 MB file limit. If you attempt to go over this limit and catch the WebException, you will see this:
Response received was -1, Microsoft.SharePoint.Client.InvalidClientQueryExceptionThe request message is too big. The server does not allow messages larger than 262144000 bytes.

In SharePoint On-Premises, you can change the Maximum Upload size (as shown above) to a maximum of 2 GB.

So Where’s the Confusion
At this writing, there are some statements in at least one article on MSDN that says things like “The maximum size of a binary file that you can add by using the REST API is 2 GB.”
This statement is technically true, but the statement applies to the underlying framework, not the Maximum Upload Size set on the Web Application. This has confused more than a few developers and there may be a generally understanding that you can use the REST endpoints for /Add and /SaveBinaryStream to get around the apparent 250 MB file size limit. This is not true, the 250 MB Maximum Upload Size limit will likely remain in effect and you will need to use the chunked file approach to upload files larger than 250 MB.

What About .NET CSOM Code?
It turns out this File Upload limit is not limited to REST endpoints. You will receive the same failure if you use a typical CSOM call with code such as the following:

static void UploadDocumentContent(string baseUrl, string libraryName, string filePath)
{
  try
  {
    ClientContext ctx = new ClientContext(baseUrl);
    ctx.Credentials = GetSharePointOnlineCredentials(baseUrl);
    Web web = ctx.Web;
    List docs = web.Lists.GetByTitle(libraryName);
    byte[] fileData = System.IO.File.ReadAllBytes(filePath);
    using (System.IO.Stream stream = new System.IO.MemoryStream(fileData))
    {
      var fci = new FileCreationInformation
      {
        Url = System.IO.Path.GetFileName(filePath),
        ContentStream = stream,
        Overwrite = true
      };
     Folder folder = docs.RootFolder;
     FileCollection files = folder.Files;
     Microsoft.SharePoint.Client.File file = files.Add(fci);
     ctx.Load(files);
     ctx.Load(file);
     ctx.ExecuteQuery();
   }
 }
 catch (Exception ex)
 {
   Console.Write(ex.ToString());
 }
}

But the exception caught above warns of a timeout exception, which is misleading. If you use Fiddler to see the response to the request to /_vti_bin/client.svc/ProcessQuery, you will see the Microsoft.SharePoint.Client.InvalidClientQueryException noted above.

Conclusion
Whether using .NET native application, .NET web applications, or client-side browser-based code, we recommend that you always use the chunked file upload approach in your applications which upload files larger than 250 MB to SharePoint Online. This approach is explained at:
https://github.com/OfficeDev/PnP/tree/dev/Samples/Core.LargeFileUpload#large-file-handling—option-3-startupload-continueupload-and-finishupload
Both .NET-based CSOM and REST enpoints fully support the StartUpload, ContinueUpload and FinishUpload methods, which are the three methods you will need to use to upload file larger than 250 MB to SharePoint Online.

Note
The StartUpload , ContinueUpload , CancelUpload and FinishUpload methods of Microsoft.SharePoint.Client.File class which are used for chunk upload are available only in SharePoint Online and SharePoint 2016 OnPremise and are not available in SharePoint 2013 OnPremise.