What's Actually Happening

Git LFS (Large File Storage) replaces large files with pointer files in Git, storing the actual content on a separate LFS server. When you clone or checkout, LFS should download the actual files. If it fails, you see pointer files instead of real content.

The Error You'll See

```bash $ git clone https://github.com/user/repo.git # Clone succeeds but large files are wrong

$ cat assets/video.mp4 version https://git-lfs.github.com/spec/v1 oid sha256:abc123def456... size 12345678 ```

Instead of binary content, you see a pointer text file.

Or during checkout:

bash
$ git lfs pull
batch response: Git LFS: "object not found"
error: failed to fetch some objects from remote

Why This Happens

  1. 1.LFS server unavailable - GitHub LFS bandwidth exceeded or server down
  2. 2.Authentication missing - LFS needs separate credentials
  3. 3.Files never pushed properly - Original push failed to upload to LFS
  4. 4.LFS not installed - Client doesn't have Git LFS installed
  5. 5.Wrong LFS endpoint - Repository configured with wrong LFS server

Step 1: Check if LFS is Installed

bash
git lfs version

If command not found:

```bash # macOS brew install git-lfs

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

# Windows # Download from https://git-lfs.github.com/

# After install, initialize git lfs install ```

Step 2: Verify LFS Tracking

Check which files should be LFS:

bash
cat .gitattributes

Should show patterns like:

bash
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text

If missing, add tracking:

bash
git lfs track "*.mp4"
git lfs track "*.zip"
git add .gitattributes

Step 3: Pull LFS Files Explicitly

```bash # Pull all LFS files for current checkout git lfs pull

# Pull specific files git lfs pull --include="assets/*.mp4"

# Pull with verbose output git lfs pull --verbose ```

Step 4: Check LFS Authentication

For private repositories, LFS needs authentication:

bash
# Check LFS endpoint
git config --get lfs.url
# Or:
git remote -v

Ensure your credentials work:

```bash # Test authentication git lfs logs

# Check for auth errors git lfs logs last ```

For GitHub, ensure you have access token:

```bash # Set up credentials git config --global credential.helper store

# Or use specific token for LFS git config --global lfs.https://github.com/.gitconfig.token your-token ```

Step 5: Check LFS Storage Status

```bash # List LFS objects in repository git lfs ls-files

# Check which files are pointers vs real git lfs status ```

Output shows:

bash
Git LFS objects to be pulled:
  assets/video.mp4 (123 MB)
  assets/image.psd (45 MB)

Step 6: Verify Remote LFS Server

Test LFS endpoint connectivity:

```bash # Get LFS URL from repo git lfs env

# Test endpoint curl -I https://github.com/user/repo.git/info/lfs ```

Should return 200 or authentication challenge.

Step 7: Re-push Missing LFS Files

If files were never properly uploaded:

```bash # Check if files need migration git lfs migrate info

# Migrate files to LFS git lfs migrate import --include="*.mp4,*.zip"

# Push LFS objects git lfs push origin main --all ```

Step 8: GitHub LFS Bandwidth Limits

If you exceeded GitHub's LFS bandwidth:

bash
batch response: This repository is over its data quota.
Purchase more data packs to restore access.
  1. 1.Options:
  2. 2.Purchase additional LFS bandwidth on GitHub
  3. 3.Use alternative LFS storage (AWS S3, self-hosted)
  4. 4.Reduce tracked file sizes

Verify the Fix

After pulling LFS files:

```bash # Check files are now real content file assets/video.mp4 # Should show: assets/video.mp4: ISO Media, MP4...

# Not pointer text head -1 assets/video.mp4 # Should NOT show: version https://git-lfs... ```

Prevention Tips

When setting up LFS:

```bash # Install LFS before cloning git lfs install

# Clone with LFS aware git lfs clone https://github.com/user/repo.git

# Or use skip and pull later git clone --skip-lfs https://github.com/user/repo.git cd repo git lfs pull ```