Bitbucket Cloud supports the Large File Storage (LFS) extension for Git that speeds up the handling of large files. It does this by replacing those large files in your Git repository with text pointer files – the pointers reference the large files, which are actually stored on a remote server.

Read more about Git Large File Storage in Bitbucket.

This page describes how to troubleshoot problems you may experience when using Git LFS with Bitbucket.


General checklist


1. Have you installed the Git LFS client on your local machine?

Each person who works with the repo has to have the Git LFS client installed on their local machine.

See Use Git LFS with Bitbucket for instructions.

2. Has Git LFS file tracking been set up, and the .gitattributes file pushed to the repo?

The repository needs to have had file tracking set up, and the updated .gitattributes file should have been pushed to the repo.

Other people who subsequently work with the repository should see that .gitattributes file in their local clone of the repo.

See Use Git LFS with Bitbucket for instructions.

3. Have you checked you have enough storage in your Bitbucket account?

Bitbucket will prevent you from pushing LFS files to the repository if doing so would exceed the storage limit for your account.

You can check the current storage used by your account by choosing Settings > Git LFS from the avatar menu in Bitbucket.

See Storage policy for Git LFS with Bitbucket for details.

Specific Git LFS errors

The Git LFS file is missing

The LFS pointer file exists in the repo, but the target file in the remote store can't be found.

In Bitbucket you'll see a 'File missing' message similar to this:

In a terminal, you may see a 404 message similar to this:

Git LFS: (0 of 1 files, 1 skipped) 0 B / 1024 B, 1024 B skipped                                  
[404] Object does not exist on the server
[ee62792aacdfe08a6f5437...8dc4eb6973d86c74c1a273] Object does not exist on the server
Possible causes
Actions you can take
The file storage server may be down.Try again later.
The file was not correctly uploaded. This can happen if Git LFS is incorrectly configured when you try to upload the file.

If you have access to the original file, try uploading it again. For example, restoring data.bin can be done by:

$ cp <source> data.bin
$ git add data.bin
$ git lfs push <remote> <branch> --all
$ git checkout data.bin

Unfortunately, you can't do anything if you don't have the original file.

Back to top

Error when pushing Git LFS file to Bitbucket

Pushing a large Git LFS file to Bitbucket.org times out and fails.

In a terminal, you may see a message similar to this:

Git LFS: (0 of 1 files) 1.60 GB / 1.60 GB
http: Put https://media-api.atlassian.io/upload/7cd73528-28e4-4c45-92a5-e6ddbf52a75e/binary?hashAlgorithm=sha2...: EOF
error: failed to push some refs to 'git@bitbucket.org:account/some_repo.git'
Possible causes
Actions you can take
Pushing a really large file (multiple gigabytes in size) times out.

Download and use our Bitbucket LFS Media Adapter.

Benefits

  • Instead of trying to upload a huge binary file at once the Bitbucket LFS Media Adapter chunks your file into 4 MB pieces. Instead of uploading gigabytes of data 4 MB chunks are uploaded.
  • Above that you'll get resumable up/downloads and de-duplication (only upload chunks that have changed).

Try again later.

Back to top

Error when pushing really large or very many files to Git LFS using SSH

Pushing really large files or a lot of files to Git LFS times out and fails when using SSH.

In a terminal, you may see a message similar to this:

Git LFS: (0 of 1 files) 1.60 GB / 1.60 GB
http: Put https://media-api.atlassian.io/upload/7cd73528-28e4-4c45-92a5-e6ddbf52a75e/binary?hashAlgorithm=sha2...: EOF
error: failed to push some refs to 'git@bitbucket.org:account/some_repo.git'
Possible causes
Actions you can take
Time out using SSH and failed to pushInstead of pushing very large or very many files to Git LFS using SSH you can try to push them with HTTPS. Generally, we recommend using HTTPS when pushing large or lots of Git LFS files.

Back to top