Safetensors header error — diagnose corruption or wrong file
Safetensors header errors mean the file is corrupted, partially downloaded, or isn't actually a safetensors file. Check file size against the repo, re-download if mismatch, fall back to checked download tools.
Diagnostic order — most likely first
Partial / interrupted download
File size doesn't match the repo's listed size. Use `ls -l` (Linux/Mac) or right-click → Properties (Windows). Compare to HuggingFace repo size.
Re-download with resume: `huggingface-cli download <repo> --resume-download`. Or delete partial: `rm -rf ~/.cache/huggingface/hub/<broken-model>` then retry.
File is actually a different format (PyTorch .bin, GGUF, etc.)
File extension is .safetensors but `file <path>` returns something else, or the first bytes don't match safetensors magic header.
Check if the repo actually has safetensors. Some older repos ship .bin (PyTorch pickle) only. Convert .bin to safetensors via `python -c 'from safetensors.torch import save_model; ...'`.
Disk corruption or filesystem issue
File loads fine on one machine, fails on another. Or fails after a system crash. SHA256 doesn't match.
Re-download from source. If repeated corruption: check disk health (`smartctl -a /dev/sdX` Linux, `wmic diskdrive get status` Windows). Filesystem-level corruption is rare but real.
Old safetensors library version
Newer model files use newer safetensors features. Loading errors mention unsupported field or format version.
Upgrade: `pip install --upgrade safetensors`. Library is highly backwards-compatible; newer versions read all older formats.
File downloaded via git clone without git-lfs
Repo cloned with `git clone` but lfs files are pointer-stubs (~135 bytes) not actual safetensors.
Install git-lfs: `apt install git-lfs` or `brew install git-lfs`. Then `git lfs install && git lfs pull` in the repo. Or just use `huggingface-cli download` instead of git.
Frequently asked questions
Why use safetensors instead of PyTorch .bin?
Safetensors is faster to load (mmap-friendly), safer (no arbitrary code execution risk vs Python pickle), and more portable (cross-language). Modern HuggingFace defaults to safetensors; .bin is legacy.
Can I convert .bin to safetensors myself?
Yes: `pip install safetensors` then `python -c 'from safetensors.torch import save_file; import torch; save_file(torch.load("model.bin"), "model.safetensors")'`. Verify with `safetensors-cli check`.
What's the smallest signal that a safetensors file is corrupt?
First 8 bytes are the header length (uint64 little-endian). If size is reasonable (< 100 MB) and first bytes parse as a valid JSON length, the header is likely intact. Beyond that, full validation requires loading.
Related troubleshooting
HuggingFace download errors split into auth (gated model, no token), rate-limit (anonymous traffic capped), or network (corporate proxy, country block). Diagnose by HTTP status code, fix per cause.
Mid-inference crashes (segfault, illegal memory access, kernel panic) usually mean VRAM ECC, thermal throttling, PSU instability, or a bad model file. Here's the diagnostic order.
When llama.cpp / Ollama outputs garbled text or repeats tokens infinitely, the tokenizer baked into the GGUF doesn't match the runtime's expectations. Here's how to confirm and fix.
When the fix is hardware
A surprising fraction of troubleshooting tickets resolve to: this card doesn't have enough VRAM for what you're asking it to do. If you're hitting OOM after every reasonable fix, or your GPU genuinely can't fit the model you need, it's upgrade time: