What's Actually Happening

You're cloning or pulling a repository that uses Git Large File Storage (LFS), but the LFS files fail to download. The repository itself downloads successfully, but the large binary files referenced by LFS are missing or corrupt, leaving you with pointer files instead of actual content.

The Error You'll See

During clone or pull:

bash
Downloading LFS objects:   0% (0/100), 0 B | 0 B/s
batch request: Missing repository: repository not found
Error downloading object: assets/video.mp4 (abc123): Smudge error

Or authentication errors:

bash
LFS: Authorization error: Credentials for the URL are missing
batch response: Git credentials for https://github.com/user/repo.git not found

Or network/timeout errors:

bash
LFS: Client error: download assets/large-file.bin: connection timeout
batch response: Post https://github.com/user/repo.git/info/lfs/objects/batch: context deadline exceeded

Or quota/missing files:

bash
Error downloading object: data/model.pkl (def456)
LFS object not found: The object may have been deleted or is still being uploaded

Why This Happens

Git LFS pull failures occur when: - LFS is not installed or not in PATH - Authentication fails for LFS requests (separate from Git authentication) - LFS bandwidth quota is exceeded - LFS storage quota is exceeded - Network connectivity issues during large file download - The LFS object was never uploaded or was deleted - Custom LFS endpoint is misconfigured - Git LFS version is incompatible with the server

Step 1: Verify Git LFS is Installed

Check if LFS is installed:

bash
git lfs version

If not found, install Git LFS:

```bash # macOS brew install git-lfs

# Ubuntu/Debian sudo apt-get install git-lfs

# Windows (with Chocolatey) choco install git-lfs

# Or download from https://git-lfs.github.com/ ```

Initialize LFS:

bash
git lfs install

Step 2: Check LFS Configuration

View LFS tracking configuration:

bash
cat .lfsconfig

Also check the .gitattributes file:

bash
cat .gitattributes

Look for LFS patterns like:

bash
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.bin filter=lfs diff=lfs merge=lfs -text

Step 3: Authenticate for LFS

LFS requires separate authentication. Set up credentials:

```bash # For GitHub, use the same credentials git config --global credential.helper manager

# Or manually authenticate git lfs logs last ```

For GitHub with 2FA, use a personal access token:

bash
git config --global credential.helper store
# Then push/pull and enter your token when prompted

Step 4: Pull LFS Objects Manually

Force LFS to pull all objects:

bash
git lfs pull

Pull specific files:

bash
git lfs pull --include="path/to/large/file.bin"

Pull with all includes:

bash
git lfs pull --include="*.mp4,*.bin"

Step 5: Fix Missing LFS Objects

If objects are missing locally:

```bash # Fetch all LFS objects git lfs fetch --all

# Pull them git lfs pull ```

For a fresh clone with LFS:

```bash # Clone without LFS first GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/user/repo.git

# Then pull LFS objects manually cd repo git lfs pull ```

Step 6: Check LFS Endpoint

Verify the LFS endpoint:

bash
git lfs env

Look for the Endpoint setting:

bash
Endpoint=https://github.com/user/repo.git/info/lfs (auth=none)

If using a custom LFS server, verify it's accessible:

bash
curl -I https://your-lfs-server.com/.git/info/lfs

Step 7: Check Quota Limits

If using GitHub LFS, check your quota:

bash
gh api user

Or check in repository settings for bandwidth and storage limits.

If over quota: - Wait for bandwidth reset (monthly) - Delete old LFS files to free storage - Upgrade your plan

Step 8: Migrate LFS Objects

If objects are missing from the LFS store, push them again:

bash
git lfs push --all origin

Or for specific commits:

bash
git lfs push --object-id origin <object-id>

Step 9: Reinstall LFS Hooks

If LFS hooks are broken:

bash
git lfs uninstall
git lfs install

This reinstalls the smudge and clean filters.

Step 10: Clean and Re-Clone

If nothing else works, clean and start fresh:

```bash # Remove LFS cache rm -rf .git/lfs

# Reset LFS git lfs uninstall git lfs install

# Pull LFS objects git lfs pull ```

Or completely re-clone:

bash
cd ..
rm -rf repo
git clone https://github.com/user/repo.git

Verify the Fix

Check that LFS files are downloaded correctly:

```bash # List LFS files git lfs ls-files

# Check file sizes (should not be ~137 bytes) ls -lh assets/*.mp4 ```

Pointer files look like:

bash
version https://git-lfs.github.com/spec/v1
oid sha256:abc123...
size 12345678

Actual files should have their real size (e.g., 50MB for a video).

Verify with checksum:

bash
sha256sum assets/large-file.bin

The hash should match the OID in the pointer.