Fix Git LFS 'repository is over its data quota' errors

Overview

When Git LFS returns “This repository is over its data quota,” the server has blocked LFS object downloads or uploads due to exceeding storage or bandwidth limits. You can:

• Unblock work temporarily by skipping LFS downloads.
• Inspect which files consume LFS.
• Reduce or remove LFS data (rewrite history or move assets elsewhere).
• Push safely and coordinate with your team.

This guide is provider-agnostic and fits Git/DevOps workflows.

Quickstart (unblock now)

If you need to clone or pull code immediately without downloading LFS objects:

# Option A: One-off clone without smudging LFS objects
GIT_LFS_SKIP_SMUDGE=1 git clone <repo-url>

# Option B: Persistently skip LFS downloads in this repo
cd <repo>
git lfs install --skip-smudge

# Optionally fetch only specific LFS paths later
git lfs fetch --include="path/to/needed.asset"

This gets the Git pointers so you can read code and run non-binary-dependent tasks (CI build steps that don’t need the assets). LFS assets won’t download until you explicitly fetch them or re-enable smudge.

Understand the quota type

• Storage quota exceeded: You have too much LFS data stored on the server.
• Bandwidth quota exceeded: You served too much LFS traffic (clones/pulls).

Fixes differ:

• For bandwidth limits, reduce downloads (skip smudge, cache in CI, avoid repeated fetches), or increase quota with your host.
• For storage limits, remove or rewrite history to make large LFS objects unreferenced, or move them out of the repository.

Inspect what’s consuming LFS

Run these in a local clone (any clone that has LFS metadata):

# List tracked LFS files (current branch)
git lfs ls-files

# List across all refs, with sizes
git lfs ls-files --all -l | sort -k3 -nr | head -n 30

# Estimate local LFS usage (by unique objects)
git lfs du

# General Git object stats (non-LFS)
git count-objects -vH

Also review .gitattributes to see what patterns are tracked via LFS:

# Example
*.zip filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

Permanent fixes (pick one or combine)

1. Buy/allocate more LFS quota

• Fastest when the data set is legitimately large.
• Still adopt CI caching and smudge skipping to save bandwidth.

1. Reduce LFS downloads (bandwidth)

• In CI, set GIT_LFS_SKIP_SMUDGE=1 and fetch only required assets.
• Share a build cache for LFS files across jobs/runners.
• Avoid full re-clones in pipelines; prefer incremental fetches.

1. Keep files but move them out of LFS (frees LFS storage)

• Convert selected LFS-tracked blobs back to regular Git blobs. This reduces LFS storage but increases Git history size. Use only if Git growth is acceptable.

# Replace LFS pointers with regular Git blobs across history for patterns
# WARNING: This rewrites history. Coordinate with your team.

git fetch --all --prune

# Ensure you have git-lfs installed
git lfs install

# Rewrite: export LFS objects for selected patterns into normal Git blobs
git lfs migrate export --include="*.zip,*.mp4"

# Force-push rewritten history
git push origin --force --all
git push origin --force --tags

1. Remove large files entirely from history (best for long-term health)

• Use git filter-repo to delete unwanted paths or strip blobs over a threshold. This frees both LFS storage and Git size once old refs are gone.

# Install git-filter-repo if needed, then:
# Remove all history of media files (example patterns)
git filter-repo --path-glob "*.mp4" --path-glob "*.zip" --invert-paths

# OR strip blobs bigger than 50 MB everywhere
# git filter-repo --strip-blobs-bigger-than 50M

# Clean up any stale LFS pointers in working tree
rm -f .git/lfs/objects -r 2>/dev/null || true

# Reinstall LFS hooks after rewrite
git lfs install

# Force-push rewritten branches and tags
git push origin --force --all
git push origin --force --tags

After a rewrite, everyone must:

• Stop pushing old refs.
• Delete local clones and re-clone, or hard-reset to the new history.
• Ensure forks and archived branches/tags that reference the old LFS objects are deleted; otherwise the server may keep counting them.

1. Adjust what is tracked by LFS

• Narrow patterns in .gitattributes to only truly binary assets.
• Remove unnecessary binaries from the repo and publish them to artifact storage, package registries, or release assets.

Minimal working example: remove large media from LFS history

Scenario: You accidentally pushed large .mp4 files to LFS. Free LFS storage by deleting them from history.

# 1) Prepare
git fetch --all --prune

# 2) Verify what’s in LFS
git lfs ls-files --all -l | grep ".mp4" | sort -k3 -nr | head

# 3) Rewrite history to drop *.mp4 everywhere
git filter-repo --path-glob "*.mp4" --invert-paths

# 4) Ensure LFS hooks are present after rewrite
git lfs install

# 5) Force-push rewritten history
git push origin --force --all
git push origin --force --tags

# 6) Team follow-up (each collaborator)
# - Delete local clone or reset hard to the new history
# - Re-clone: GIT_LFS_SKIP_SMUDGE=1 git clone <repo-url>

Result: The server will see those LFS objects become unreferenced and reclaim storage after its GC window. Usage reporting may lag.

Step-by-step checklist

1. Decide whether you need a temporary unblock (skip smudge) or a permanent fix (rewrite/remove or purchase quota).
2. Measure current LFS usage and identify the worst offenders.
3. Choose a strategy: export from LFS to Git, or remove from history with git filter-repo.
4. Coordinate a maintenance window; warn collaborators about force-pushes.
5. Rewrite and force-push all branches and tags.
6. Delete obsolete branches/tags and old forks that still reference the data.
7. Have everyone re-clone; re-run CI with GIT_LFS_SKIP_SMUDGE=1 if bandwidth is tight.
8. Tighten .gitattributes and repository policies to prevent regressions.

Pitfalls and gotchas

• Force-pushes will close or invalidate open PRs. Communicate clearly.
• git lfs prune only cleans local clones; it does not free server storage.
• Server-side usage dashboards may lag after rewrites; allow time for GC.
• Any ref (tags, branches, forks) that still points to old commits keeps LFS data alive on the server.
• Converting LFS to Git blobs may unblock you but can bloat the repo and slow clones.
• CI systems that re-clone each job can burn bandwidth quickly; cache LFS.

Performance notes

• Keep large, frequently changing binaries out of Git history. Store them externally and fetch at build time.
• Use GIT_LFS_SKIP_SMUDGE=1 by default in CI; fetch only needed assets.
• Favor narrow LFS patterns; avoid tracking entire directories if only a subset is needed.
• Consider Git partial clone and sparse-checkout for non-LFS content to reduce network and disk I/O.

Tiny FAQ

• Q: Will deleting files on the default branch free LFS storage? A: Only if those files are removed from all refs (branches, tags, forks). Otherwise they’re still counted.

• Q: Does git lfs prune free server space? A: No. It only removes unreferenced LFS objects from your local cache.

• Q: How long until usage drops after a rewrite? A: It depends on the host’s GC schedule. Expect some delay; ensure no refs still point to old commits.

• Q: I don’t own the repo. What can I do? A: Clone with GIT_LFS_SKIP_SMUDGE=1 and ask maintainers to add quota or clean history.

• Q: How do I prevent recurrence? A: Tighten .gitattributes, add pre-receive/CI checks for large files, and use external storage for big binaries.