Upload file to Downloads section failing with 401/400 for large files

Question

Hi

I'm tying to upload files to the Downloads section and have noticed some inconsistent behavior. Smaller files upload successfully, but when I attempt to upload larger files (still under 1 GB), the operation consistently fails with either a 401 Unauthorized error or a 400 Temporary Failure error.

I have a few questions and would appreciate any insights:

* Under what conditions does the service return a 401 Unauthorized error?

Since I can successfully upload smaller files using the same account and workflow, it doesn't appear to be a permissions issue. Could this be a misleading error that is actually triggered by another condition, such as file size, timeout, or storage limits? 
* What is the maximum allowed size for a single file in the Downloads category? I've found conflicting information in various sources. Some documentation mentions a 1 GB per-file limit, while others reference 2 GB. Is there a documented per file and overall storage limit at the Downloads?
* I currently have no uploaded files in the Downloads section, and repository reports a size of approximately 2.6 GB.

I see a notice in the Downloads section (see picture below) that reads if repository size exceeds 2GB it becomes read-only, but how is it allowing to upload of small files?

Based on my understanding Downloads size is not counted in source repository size but correct me if this is not correct understanding.
* Manual upload of large files is also failing silently with no error though I ignored it because it suggested using api for large uploads.
* Url used to upload is: https://api.bitbucket.org/2.0/repositories/<enterpriseError rpo>/downloads
*

Any clarification or guidance would be greatly appreciated.

Thanks,

Atul

a2l · Answer

If repository size of 4GB is allowed, isn't this warning message confusing and misleading?

This repository's size is over 2 GB. If it reaches 2 GB, we'll restrict the repository to read-only access.

a2l · Answer

Thanks Josh. I'm reaching out to Support team.

* Using scoped token created on repository and has write access
* Size is well within 1GB limit (~795MB)
* Since files are well within 1GB limit and it is failing consistently, I have captured both failure and success verbose logs and time, and I'll be reaching out to support soon.

-Atul

Josh · Answer

Hi Atul, a few corrections and clarifications, because the limits are easy to mix up:

* Please don't switch to an app password. Bitbucket Cloud app passwords were fully removed on July 28, 2026 (after brownouts starting June 9), and requests using them now fail with 401. Use an Atlassian API token with Bitbucket scopes instead (write:repository:bitbucket for uploads), with your Atlassian account email as the username. A repository or workspace access token also works. Since your small uploads succeed with the same credentials, your auth setup itself is probably fine.
* 1 GB vs 2 GB: Atlassian's "repository and file size limits" page lists uploading files as "must be no larger than 1 GB". The 2 GB figure on that page is for downloading archive .zip files from the Downloads page. So 1 GB per uploaded file is the number to plan around.
* Repository size: 2 GB is a warning threshold. The limit where pushes get disabled is 4 GB, so a 2.6 GB repo is not read-only yet. As far as I know, files in Downloads are stored separately and don't add to the Size shown under Repository details.

For the large-file failures, I'd first check whether it's a timeout rather than a real auth failure. Run the upload with verbose output and see how long it runs before it fails:

curl -v -X POST "https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO/downloads" \
  --user "you@company.com:$ATLASSIAN_API_TOKEN" \
  --form files=@build.zip

If files near the 1 GB mark fail after a similar amount of time each run, while smaller ones succeed, you're most likely hitting a long single-request upload being cut off, and the status code you get back isn't very meaningful. Practical options:

* Compress harder or split the artifact into parts of a few hundred MB (e.g. split -b 400M build.zip build.zip.part-, then cat build.zip.part-* > build.zip on the other side) and upload each part.
* For release binaries that are regularly this big, publish them to S3 or similar storage and put the link in your release notes. Bitbucket's docs point that way too for large binaries.

If a file comfortably under 1 GB still fails consistently with an API token, open a ticket with Bitbucket support and include the UTC timestamp and the response body. They can see what rejected the request on their side.