Introduction

GitLab LFS (Large File Storage) tracks large files in a separate storage system with quota limits at the namespace level. When the total LFS storage usage exceeds the configured quota, all LFS object pushes are rejected. This blocks developers from pushing commits containing large files and can halt design, data science, and game development workflows.

Symptoms

  • git push fails during LFS object upload phase
  • Error message mentions quota or storage limit exceeded
  • Git LFS push works for small files but fails for larger ones
  • Namespace storage page shows LFS usage at or above the quota limit
  • Error message: batch response: LFS objects quota exceeded for this namespace

Common Causes

  • LFS quota set too low for the team's large file needs
  • Accumulated LFS objects from old branches and commits consuming quota
  • Large dataset or binary files committed via LFS exceeding the plan limits
  • Multiple projects in the namespace sharing the same quota pool
  • Free tier GitLab instance with restrictive LFS storage limits

Step-by-Step Fix

  1. 1.Check current LFS storage usage: See how much quota is consumed.
  2. 2.`
  3. 3.# GitLab UI: Settings > Usage Quotas
  4. 4.# Check LFS storage usage and limit
  5. 5.# Or via API
  6. 6.curl --header "PRIVATE-TOKEN: $TOKEN" \
  7. 7."https://gitlab.example.com/api/v4/groups/$GROUP_ID" | jq '.lfs_size_limit, .lfs_size'
  8. 8.`
  9. 9.Remove unused LFS objects to free quota: Clean up orphaned LFS data.
  10. 10.```bash
  11. 11.# Find large LFS objects
  12. 12.git lfs ls-files --long --all | sort -k3 -rn | head -20
  13. 13.# Remove LFS objects not referenced by any branch
  14. 14.git lfs prune
  15. 15.`
  16. 16.Increase the LFS quota if possible: Upgrade or request more storage.
  17. 17.`
  18. 18.# GitLab Admin: Admin > Settings > General > LFS
  19. 19.# Increase the LFS size limit for the namespace
  20. 20.# Or upgrade GitLab plan for higher limits
  21. 21.`
  22. 22.Rewrite history to remove large files from the repository: Reduce LFS usage permanently.
  23. 23.```bash
  24. 24.# Use git-filter-repo to remove large files from history
  25. 25.pip install git-filter-repo
  26. 26.git filter-repo --invert-paths --path large-file.bin --path data/
  27. 27.# Force push the cleaned history
  28. 28.git push --force origin main
  29. 29.`
  30. 30.Move large files to external storage: Use alternatives to LFS.
  31. 31.`
  32. 32.# Store large files in:
  33. 33.# - GitLab Package Registry
  34. 34.# - External object storage (S3, GCS)
  35. 35.# - GitLab Releases for binary artifacts
  36. 36.`

Prevention

  • Set up LFS quota monitoring and alert at 80% usage
  • Establish guidelines for what should be tracked via LFS vs. external storage
  • Regularly prune unused LFS objects from repositories
  • Use .gitattributes to explicitly control which file types use LFS
  • Consider self-managed GitLab with custom LFS storage limits for large teams
  • Implement pre-commit hooks that warn when adding large files to the repository