# ValueError: safetensors metadata mismatched: expected 1024 tensors, got 1023

- **ID:** `huggingface/safetensors-metadata-mismatch`
- **Domain:** huggingface
- **Category:** data_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

The safetensors file header metadata declares a different number of tensors than are actually stored in the file, typically due to incomplete download or corrupted checkpoint.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| safetensors>=0.3.0 | active | — | — |
| transformers>=4.30.0 | active | — | — |
| huggingface-hub>=0.16.0 | active | — | — |

## Workarounds

1. **Clear the Hugging Face cache and re-download the model: `rm -rf ~/.cache/huggingface/hub/models--org--model-name/` then `from transformers import AutoModel; AutoModel.from_pretrained('org/model-name')`** (90% success)
   ```
   Clear the Hugging Face cache and re-download the model: `rm -rf ~/.cache/huggingface/hub/models--org--model-name/` then `from transformers import AutoModel; AutoModel.from_pretrained('org/model-name')`
   ```
2. **Use the huggingface_hub CLI to force re-download: `huggingface-cli download org/model-name --cache-dir /tmp/new-cache --local-dir ./model --force-download`** (85% success)
   ```
   Use the huggingface_hub CLI to force re-download: `huggingface-cli download org/model-name --cache-dir /tmp/new-cache --local-dir ./model --force-download`
   ```
3. **If the file is partially downloaded, use `wget -c` to resume: `wget -c https://huggingface.co/org/model-name/resolve/main/model.safetensors`** (75% success)
   ```
   If the file is partially downloaded, use `wget -c` to resume: `wget -c https://huggingface.co/org/model-name/resolve/main/model.safetensors`
   ```

## Dead Ends

- **Re-download the same file without clearing cache** — If the cached file is corrupted, re-downloading to the same cache path without clearing will reuse the broken file. (70% fail)
- **Manually editing the safetensors metadata with a hex editor** — Safetensors files are integrity-checked; any manual tampering causes a checksum error and breaks loading entirely. (95% fail)
- **Upgrading transformers to the latest version** — The error originates from the safetensors library, not transformers; upgrading transformers alone does not fix the corrupted file. (60% fail)