{
  "id": "huggingface/safetensors-metadata-mismatch",
  "signature": "ValueError: safetensors metadata mismatched: expected 1024 tensors, got 1023",
  "signature_zh": "ValueError: safetensors 元数据不匹配：期望 1024 个张量，实际得到 1023 个",
  "regex": "ValueError: safetensors metadata mismatched: expected \\d+ tensors, got \\d+",
  "domain": "huggingface",
  "category": "data_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "safetensors 文件头部元数据声明的张量数量与实际文件中存储的张量数量不一致，通常是由于下载不完整或检查点损坏导致。",
  "versions": [
    {
      "version": "safetensors>=0.3.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "transformers>=4.30.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "huggingface-hub>=0.16.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Re-download the same file without clearing cache",
      "why_fails": "If the cached file is corrupted, re-downloading to the same cache path without clearing will reuse the broken file.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Manually editing the safetensors metadata with a hex editor",
      "why_fails": "Safetensors files are integrity-checked; any manual tampering causes a checksum error and breaks loading entirely.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Upgrading transformers to the latest version",
      "why_fails": "The error originates from the safetensors library, not transformers; upgrading transformers alone does not fix the corrupted file.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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')`",
      "success_rate": 0.9,
      "how": "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')`",
      "condition": "",
      "sources": []
    },
    {
      "action": "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`",
      "success_rate": 0.85,
      "how": "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`",
      "condition": "",
      "sources": []
    },
    {
      "action": "If the file is partially downloaded, use `wget -c` to resume: `wget -c https://huggingface.co/org/model-name/resolve/main/model.safetensors`",
      "success_rate": 0.75,
      "how": "If the file is partially downloaded, use `wget -c` to resume: `wget -c https://huggingface.co/org/model-name/resolve/main/model.safetensors`",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "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')`",
    "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`",
    "If the file is partially downloaded, use `wget -c` to resume: `wget -c https://huggingface.co/org/model-name/resolve/main/model.safetensors`"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://huggingface.co/docs/safetensors/en/troubleshooting#metadata-mismatch",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-11-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}