{
  "id": "huggingface/cache-corruption-safetensors",
  "signature": "OSError: Error while deserializing header: HeaderTooLarge",
  "signature_zh": "OSError: 反序列化头部时出错：HeaderTooLarge",
  "regex": "OSError: Error while deserializing header: HeaderTooLarge",
  "domain": "huggingface",
  "category": "system_error",
  "subcategory": null,
  "root_cause": "The safetensors file in the Hugging Face cache is corrupted, often due to incomplete download, disk write errors, or concurrent access by multiple processes.",
  "root_cause_type": "generic",
  "root_cause_zh": "Hugging Face缓存中的safetensors文件损坏，通常由下载不完整、磁盘写入错误或多个进程并发访问导致。",
  "versions": [
    {
      "version": "safetensors 0.4.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "transformers 4.42.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "huggingface-hub 0.23.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The file on disk is corrupted, not the library; reinstalling doesn't fix the cache.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The error is about a corrupted file header, not resource exhaustion.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Clear the Hugging Face cache for the specific model and re-download:\n\nimport shutil\nfrom pathlib import Path\ncache_dir = Path.home() / '.cache' / 'huggingface' / 'hub'\n# Find and remove the corrupted model folder (e.g., models--bert-base-uncased)\nshutil.rmtree(cache_dir / 'models--bert-base-uncased')\n# Then reload the model\nfrom transformers import AutoModel\nmodel = AutoModel.from_pretrained('bert-base-uncased')",
      "success_rate": 0.85,
      "how": "Clear the Hugging Face cache for the specific model and re-download:\n\nimport shutil\nfrom pathlib import Path\ncache_dir = Path.home() / '.cache' / 'huggingface' / 'hub'\n# Find and remove the corrupted model folder (e.g., models--bert-base-uncased)\nshutil.rmtree(cache_dir / 'models--bert-base-uncased')\n# Then reload the model\nfrom transformers import AutoModel\nmodel = AutoModel.from_pretrained('bert-base-uncased')",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use `huggingface-cli` to delete the model from cache: `huggingface-cli delete-cache` and select the corrupted model, then re-download with `from_pretrained`.",
      "success_rate": 0.8,
      "how": "Use `huggingface-cli` to delete the model from cache: `huggingface-cli delete-cache` and select the corrupted model, then re-download with `from_pretrained`.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "清除特定模型的Hugging Face缓存并重新下载：\n\nimport shutil\nfrom pathlib import Path\ncache_dir = Path.home() / '.cache' / 'huggingface' / 'hub'\n# 找到并删除损坏的模型文件夹（例如 models--bert-base-uncased）\nshutil.rmtree(cache_dir / 'models--bert-base-uncased')\n# 然后重新加载模型\nfrom transformers import AutoModel\nmodel = AutoModel.from_pretrained('bert-base-uncased')",
    "使用 `huggingface-cli` 从缓存中删除模型：`huggingface-cli delete-cache` 并选择损坏的模型，然后使用 `from_pretrained` 重新下载。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://huggingface.co/docs/safetensors/en/faq#corrupted-files",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-06-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}