Troubleshooting Git LFS Smudge Errors: Why Repositories Only Clone 130-Byte Pointer Files

❓ Recurrence of phenomenon: Why is a model with dozens of GB only 130 bytes?

Many developers often encounter a confusing phenomenon when using git clone https://huggingface.co/...: the code is cloned in a few seconds, but an error OSError: Unable to load weights from file is reported when the model is loaded.

When you use cat to open these weight files, you will find that their contents are similar to the following:

version https://git-lfs.github.com/spec/v1
oid sha256:7b5d12a8f9024c16a6b571d87e025f1874258b3874c935d21b7642e128cb5219
size 15420317800

This is a typical Git LFS pointer file (Pointer File). The actual model binary stream is not pulled down at all!

🔬 Git LFS filter (Smudge vs Clean) principle

Git is a system designed for plain text version control. In order to support large files of several gigabytes, the Git community introduced the git-lfs extension, whose core mechanism relies on Git's two major hook filters:

• Clean Filter (commit phase): When you commit a large file, LFS calculates its SHA256, stages the large file and replaces it with a small hundred-byte pointer written to the Git tree.
• Smudge Filter (checkout phase): When you check out a branch, Git automatically calls git-lfs smudge to request the remote LFS bucket via HTTP to download the real files and restore them to the workspace.

Why is the Smudge error triggered? When you git clone across an ocean or an unstable network, Smudge is executed serially and synchronously. A single HTTP request timeout will cause Smudge to throw Error: smudge filter failed and terminate. At this time, Git can only leave a small pointer file on your disk.

🔨 Three radical solutions

📌 Option 1: Give up Git Clone and embrace huggingface-cli (officially recommended)

For large models, Git's version tree tracking is often redundant and energy-consuming. Officials strongly recommend using huggingface-cli instead of git clone:

# No matter how many times the network is interrupted, the download can be resumed without loss when re-executed.
export HF_ENDPOINT="https://hf-mirror.net"
huggingface-cli download openai/whisper-large-v3 \
  --local-dir ./whisper-large-v3 \
  --local-dir-use-symlinks False

📌 Option 2: Two-stage cloning (skip Smudge, post-mirror replenishment)

If you must use the Git warehouse structure, you can use GIT_LFS_SKIP_SMUDGE=1 to pull the code metadata in seconds, and then use the mirror source to accurately pull the large file:

# Stage 1: Clone only Git metadata and code, skipping all large file downloads of tens of gigabytes
GIT_LFS_SKIP_SMUDGE=1 git clone https://hf-mirror.net/openai/whisper-large-v3.git
cd whisper-large-v3

# Phase 2: Pulling LFS binary assets individually
git lfs pull

📌 Option 3: Write a script to check whether the disk contains fake files with one click

The following shell script can scan all safetensors/bin files smaller than 1KB in the specified model directory and immediately confirm whether there are any pointers left that have not been successfully pulled:

find . -type f \( -name "*.safetensors" -o -name "*.bin" \) -size -1k -exec ls -lh {} + \
  -exec echo "Warning: A pointer dummy file was found and needs to be redrawn!" \;