Uploading Very Large Files (Increasing the Maximum Upload Size)

TLDR - Quick Summary

What: Raise SFTP Gateway's maximum single-file upload size when your cloud connection writes to Azure Blob Storage.

Why a limit exists: a block blob can have at most 50,000 blocks, so block size × 50,000 = the largest single blob. The default block size (4 MB) caps a single file at ~200 GB. Azure File Share connections are not affected; Azure allows files up to about 4 TB there.

Symptom: a file larger than the maximum fails partway through, and most SFTP clients retry from the beginning — so it looks like the transfer "keeps restarting."

Fix: raise features.file-system.azure.block-size-mb. Larger blocks use more heap, so give the backend more memory.

Apply: container — set an environment variable and restart; VM/marketplace — edit application.properties and run service sftpgw-admin-api restart.

Go further: SFTP Gateway for the Enterprise

Running secure file transfer at enterprise scale? Our free white paper covers high-availability SFTP Gateway architecture, security and compliance, and cloud integration across AWS, Azure, and Google Cloud.

👉 Download the SFTP Gateway white paper — free; a short registration unlocks the PDF.

Overview

SFTP Gateway uploads files to Azure Blob Storage in blocks: each file is sent as a series of blocks that Azure commits into one block blob. The block size is configurable, and Azure allows at most 50,000 blocks per blob, so block size × 50,000 = the largest single file SFTP Gateway can upload. At the default 4 MB block size, that is about 200 GB.

If a file is larger than that maximum, the upload fails partway through and most SFTP clients retry from the beginning, so it looks like the transfer "keeps restarting." Increasing the block size raises the ceiling.

Azure File Share connections work differently and have no block setting to tune. Azure supports files up to about 4 TB on a file share, so no change is needed there.

This article extends the Application Properties reference. For broader throughput and memory tuning, see Performance Tuning SFTP Gateway.

Default Azure limits

Storage	Setting	Default	Block limit	Default max single file
Azure Blob	features.file-system.azure.block-size-mb (MB)	4 MB	50,000 blocks	about 200 GB
Azure File Share	not configurable	4 MB	not applicable	about 4 TB (Azure limit)

Choosing a block size

Maximum file size = block size × 50,000. So the block size you need is your largest expected file divided by 50,000.

Block size	Property value (MB)	Maximum single file
4 MB (default)	4	about 200 GB
16 MB	16	about 800 GB
100 MB	100	about 4.7 TB

How to change the setting

Container edition (Docker, Kubernetes, AKS)

Set the environment variable on the SFTP Gateway backend container and restart it. The value is in MB.

Environment variable	Example value
FEATURES_FILESYSTEM_AZURE_BLOCKSIZEMB	100 (100 MB)

VM and marketplace editions

Add the property to /opt/sftpgw/application.properties on the VM:

features.file-system.azure.block-size-mb=100

Then apply the change with:

service sftpgw-admin-api restart

Connections to other clouds

The setting applies to the storage behind a cloud connection, not to the VM. An SFTP Gateway instance can have connections to more than one provider, and the block size above only affects Azure Blob connections. If this instance also writes to Amazon S3, the part size is a separate setting covered in Increasing Max Upload File Size (AWS). Google Cloud Storage needs no change; it already supports single files up to about 5 TB (see the Google Cloud article).

Important: memory

⚠️ Larger pieces use more memory. Each piece of an in-progress upload is held in the SFTP Gateway backend's memory while it transfers. As a rough guide, allow about five times the piece size of memory for each large upload happening at the same time. If you set a large piece size, or expect many large uploads at once, give the backend more memory (a larger container memory limit or a larger VM).

For the heap-sizing procedure, see Configuring VM Memory Settings and the memory section of Performance Tuning SFTP Gateway.