Introduction

Git LFS (Large File Storage) replaces large files with text pointers in the repository and stores the actual file content on a separate server. During clone, LFS downloads the actual files, and this process can fail for various reasons:

bash
git clone https://github.com/org/large-repo.git
# Cloning into 'large-repo'...
# Downloading LFS objects: 45% (9/20), 1.2 GB / 2.8 GB
# batch response: Authentication required
# error: failed to fetch some objects from 'https://github.com/org/large-repo.git/info/lfs'

Symptoms

  • Clone completes but LFS files are pointer text instead of actual content
  • Download fails partway through with authentication errors
  • Some LFS objects download but others fail
  • "batch response" errors from the LFS server
  • Repository clone works but LFS objects return 404 or 403

Common Causes

  • Git LFS credentials not configured or expired
  • LFS bandwidth limits or transfer quotas exceeded
  • LFS server unavailable or rate-limiting requests
  • Corrupted LFS pointer files in the repository
  • Large number of LFS objects overwhelming the download process

Step-by-Step Fix

  1. 1.Verify Git LFS is installed:
  2. 2.```bash
  3. 3.git lfs version
  4. 4.# Should show: git-lfs/3.x.x
  5. 5.`
  6. 6.If not installed:
  7. 7.```bash
  8. 8.sudo apt install git-lfs
  9. 9.git lfs install
  10. 10.`
  11. 11.Re-download failed LFS objects after a partial clone:
  12. 12.```bash
  13. 13.cd large-repo
  14. 14.git lfs fetch --all
  15. 15.git lfs checkout
  16. 16.`
  17. 17.Fix authentication issues. For GitHub:
  18. 18.```bash
  19. 19.# Use a personal access token
  20. 20.git config --global lfs.https://github.com/org/large-repo.git/info/lfs.access basic
  21. 21.git config --global user.password YOUR_TOKEN
  22. 22.`
  23. 23.Or use the GitHub CLI:
  24. 24.```bash
  25. 25.gh auth login
  26. 26.`
  27. 27.Reduce concurrent transfers to avoid rate limiting:
  28. 28.```bash
  29. 29.git config --global lfs.concurrenttransfers 3
  30. 30.`
  31. 31.Then retry:
  32. 32.```bash
  33. 33.git lfs fetch --all
  34. 34.git lfs checkout
  35. 35.`
  36. 36.Clone without LFS first, then fetch LFS separately:
  37. 37.```bash
  38. 38.GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/org/large-repo.git
  39. 39.cd large-repo
  40. 40.git lfs fetch --all
  41. 41.git lfs checkout
  42. 42.`
  43. 43.This separates the git clone from the LFS download, making it easier to retry just the LFS part.

Prevention

  • Always run git lfs install before working with LFS repositories
  • Use GIT_LFS_SKIP_SMUDGE=1 for initial clone of very large repos
  • Configure LFS authentication via credential helpers (git config --global credential.helper store)
  • Monitor LFS bandwidth usage on hosting platforms (GitHub, GitLab)
  • Keep LFS pointer files valid by not editing them manually
  • Use git lfs migrate to properly add large files to LFS tracking
  • Test LFS clone/recovery in CI/CD pipelines to detect authentication issues early
  • Document LFS requirements (installation, authentication, bandwidth) in your project README