Bitbucket Cloud · Pipelines · Checked November 2, 2026

Bitbucket Pipelines: Git LFS files that arrive as pointers

Pipelines does not download Git LFS files unless you ask for them. When LFS support came to Pipelines in 2018, Atlassian kept that default because LFS files "can be slow to download and not needed for many types of builds" (Atlassian's announcement). In the step's clone, each LFS file is a short text file, a pointer, and whatever opens it fails. We made a clone that skips LFS with git-lfs 3.7 and opened a zip from it:

$ cat assets.zip
version https://git-lfs.github.com/spec/v1
oid sha256:031d5c8db194a1936ab800a2f24e8c4642182e51d0d95775137cfc8cf55b12ea
size 5108

$ unzip -l assets.zip
Archive:  assets.zip
  End-of-central-directory signature not found.  Either this file is not
  a zipfile, or it constitutes one disk of a multi-part archive. …

$ python -c "import zipfile; zipfile.ZipFile('assets.zip')"
zipfile.BadZipFile: File is not a zip file

Is it a pointer?

The clone in Build setup runs with GIT_LFS_SKIP_SMUDGE=1, as a step log posted in a 2022 community thread shows (see Build setup takes too long). Two checks you can put in the script:

script:
  - head -c 120 assets.zip
  - git lfs ls-files

A pointer starts with version https://git-lfs.github.com/spec/v1, and its last line is the size of the real file. git lfs ls-files marks each file: a - after the ID means a pointer, a * means the full file. Our clone printed 031d5c8db1 - assets.zip, and 031d5c8db1 * assets.zip after git lfs pull. That check needs git-lfs in the image; without it, Git answers git: 'lfs' is not a git command.

git status stays empty. The pointer is what the commit holds, so Git sees nothing missing.

lfs: true on the step that needs it

pipelines:
  default:
    - step:
        name: Build
        clone:
          lfs: true
        script:
          - unzip assets.zip

Under clone: at the top of the file, it applies to every step, and each step downloads every LFS file at its start. Atlassian's Git clone behavior recommends turning it on per step, or downloading only the files a step needs, to cut build time and resource use. Large LFS files also fill the build's disk ("No space left on device").

Only one file

The same page has an example for a step that needs one file. It leaves lfs off, installs git-lfs and pulls that file by name:

    - step:
        clone:
          lfs: false
        script:
          - apt-get update && apt-get install -y git-lfs
          - git lfs pull --include=assets.zip

Atlassian's example adds no credentials for this download. apt-get works in Debian and Ubuntu images; for another image, install git-lfs its own way, or build your own image with it.

"'git-lfs' was not found on your path" when the step pushes

A step with lfs: true that commits and pushes needs git-lfs in its image. Without it, the push stops with:

This repository is configured for Git LFS but 'git-lfs' was not found on your path. If you no longer wish to use Git LFS, remove this hook by deleting the 'pre-push' file in the hooks directory (set by 'core.hookspath'; usually '.git/hooks').
error: failed to push some refs to …

The message comes from the pre-push hook that git lfs install writes into a repository; we read it in our clone's .git/hooks/pre-push. Atlassian's article Pipelines failing with "This repository is configured for Git LFS but 'git-lfs' was not found on your path" installs git-lfs in the step's script, or in your own image so it isn't installed on every build. Deleting the hook, as the message offers, means git-lfs no longer uploads the LFS files of the commits you push.

Pushing LFS files back with the default credentials

With git-lfs installed, a push of a commit with a new LFS file can still fail. Atlassian's article How to push LFS files using Bitbucket Pipelines? shows:

fatal: could not read Username for 'https://bitbucket.org': No such device or address
…
error: failed to push some refs to …

The credentials Pipelines sets up for the step's own repository don't allow LFS pushes. Atlassian tracks it as BCLOUD-23180, a bug open since March 2024. The article gives two other ways to push:

An API token with the write:repository:bitbucket scope, kept in secured variables: git push "https://${BB_USER}:${BB_API_TOKEN}@bitbucket.org/${BITBUCKET_REPO_FULL_NAME}.git". Push back to your repository asks for read:repository:bitbucket as well.
SSH: git remote set-url origin "$BITBUCKET_GIT_SSH_ORIGIN". The same page adds the repository's Pipelines SSH key to your personal SSH keys so it can push.

The article's commit message starts with [skip ci], so the push does not start another pipeline.

A file that cannot be downloaded

When a download fails with "Object does not exist on the server", Atlassian's Troubleshoot Git LFS in Bitbucket gives two causes: the pointer is in the repository but the file never reached the LFS store, or the store was down for a while. For the first, upload the file again from the original; without the original, it can't be recovered. The same article notes that Bitbucket refuses LFS pushes that would go over the workspace's storage limit; workspace admins see the usage under Workspace settings, Git LFS.

Bitbucket Pipelines in IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window, with their steps, the failed step and the command it stopped at, and the step's log as Bitbucket writes it. The list, steps and logs are free; running, re-running and stopping pipelines are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian or JetBrains.

More: Git commands that fail in a shallow clone (origin/main, git describe) · The scheduled pipeline did not run · "Container 'build' failed to pull image" · "Connection refused" to a service (MySQL, PostgreSQL, Redis) · "Not authorized to perform sts:AssumeRoleWithWebIdentity" (OIDC to AWS) · Test results not showing · A variable is empty · "Host key verification failed" (SSH) · "Cannot connect to the Docker daemon" · "authorization denied by plugin pipelines" (Docker) · "Container 'docker' exceeded memory limit." · Pipelines did not run after a push · "Container 'Build' exceeded memory limit." · "Exceeded build time limit of 120 minutes" · The cache is not used · "unexpected system error" · "command not found" · Submodules not cloned · "We couldn't clone the repository" · "No online runner available" · "No space left on device" · "Step exceeded processing limits" · The artifact is missing in the next step · The build passed before and fails now · Build setup takes too long · "You've run out of build minutes" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · A step skipped by condition: changesets (includePaths) · Parallel steps that keep running after one fails (fail-fast) · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語