{"record":{"id":"8703f7b4d1e39362","repo":"deepseek-ai/DeepSeek-V3","slug":"key-key-not-found-in-mapping","errorCode":null,"errorMessage":"Key ${key} not found in mapping","messagePattern":"Key (.+?) not found in mapping","errorType":"validation","errorClass":"AssertionError","httpStatus":null,"severity":"error","filePath":"inference/convert.py","lineNumber":63,"sourceCode":"    \"\"\"\n    torch.set_num_threads(8)\n    n_local_experts = n_experts // mp\n    state_dicts = [{} for _ in range(mp)]\n\n    for file_path in tqdm(glob(os.path.join(hf_ckpt_path, \"*.safetensors\"))):\n        with safe_open(file_path, framework=\"pt\", device=\"cpu\") as f:\n            for name in f.keys():\n                if \"model.layers.61\" in name:\n                    continue\n                param: torch.Tensor = f.get_tensor(name)\n                if name.startswith(\"model.\"):\n                    name = name[len(\"model.\"):]\n                name = name.replace(\"self_attn\", \"attn\")\n                name = name.replace(\"mlp\", \"ffn\")\n                name = name.replace(\"weight_scale_inv\", \"scale\")\n                name = name.replace(\"e_score_correction_bias\", \"bias\")\n                key = name.split(\".\")[-2]\n                assert key in mapping, f\"Key {key} not found in mapping\"\n                new_key, dim = mapping[key]\n                name = name.replace(key, new_key)\n                for i in range(mp):\n                    new_param = param\n                    if \"experts\" in name and \"shared_experts\" not in name:\n                        idx = int(name.split(\".\")[-3])\n                        if idx < i * n_local_experts or idx >= (i + 1) * n_local_experts:\n                            continue\n                    elif dim is not None:\n                        assert param.size(dim) % mp == 0, f\"Dimension {dim} must be divisible by {mp}\"\n                        shard_size = param.size(dim) // mp\n                        new_param = param.narrow(dim, i * shard_size, shard_size).contiguous()\n                    state_dicts[i][name] = new_param\n\n    os.makedirs(save_path, exist_ok=True)\n\n    for i in trange(mp):\n        save_file(state_dicts[i], os.path.join(save_path, f\"model{i}-mp{mp}.safetensors\"))","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py#L45-L81","documentation":"Thrown in convert.py's main loop (inference/convert.py:63): after renaming HF-style parameter names (self_attn→attn, mlp→ffn, weight_scale_inv→scale, e_score_correction_bias→bias), it takes the second-to-last dot component (key = name.split('.')[-2]) and looks it up in the hardcoded `mapping` dict (embed_tokens, q_proj, kv_a_proj_with_mqa, gate, down_proj, ...). Any checkpoint whose module names differ from the expected HF DeepSeek-V3 layout fails here.","triggerScenarios":"Running convert.py --hf-ckpt-path with: a checkpoint from a different/newer HF model revision that renamed modules (e.g. new attention or quantization keys), a DeepSeek-R2/other-variant checkpoint with keys like xxx not in mapping, a plain (non-HF) safetensors file, or names where the replacement chain produces an unexpected second-to-last token (e.g. after 'mlp'→'ffn', 'gate_proj'→... the split lands on something unmapped like 'e_score_correction_bias' paths where key becomes 'bias' before mapping).","commonSituations":"Upgrading transformers/HF checkpoint revisions where naming changed; converting V2/V3.1/V3.2-Exp checkpoints whose router or expert-parallel keys differ; scale tensors named differently (weight_scale vs weight_scale_inv) so 'scale' key never appears or an unknown key appears.","solutions":["Inspect the failing key: print the original tensor name that produced it (add logging before the assert) and compare with mapping's keys","Extend the mapping dict in convert.py with the missing key: 'new_module_name': ('target_name', shard_dim_or_None)","Verify you are converting a checkpoint with the exact naming this script targets (DeepSeek-V3 HF format); for other revisions use the upstream repo's matching convert script","Check for rename collisions: name.replace('gate', ...) style substring bugs — prefer exact component replaces"],"exampleFix":"# before (convert.py)\nmapping = {\n    ...\n    \"gate\": (\"gate\", None),\n}\n# AssertionError: Key xxx not found in mapping\n\n# after — add the missing module key with its new name and shard dim\nmapping = {\n    ...\n    \"gate\": (\"gate\", None),\n    \"xxx\": (\"yyy\", 0),  # shard dim 0 for column-parallel, 1 for row-parallel, None for replicated\n}","handlingStrategy":"validation","validationCode":"from safetensors import safe_open\nfrom convert import mapping\n\nwith safe_open(\"model-00001-of-000163.safetensors\", framework=\"pt\") as f:\n    bad = set()\n    for name in f.keys():\n        n = name[len(\"model.\"):] if name.startswith(\"model.\") else name\n        n = n.replace(\"self_attn\", \"attn\").replace(\"mlp\", \"ffn\") \\\n             .replace(\"weight_scale_inv\", \"scale\").replace(\"e_score_correction_bias\", \"bias\")\n        key = n.split(\".\")[-2]\n        if key not in mapping:\n            bad.add((name, key))\n    assert not bad, f\"unmapped keys: {sorted(bad)[:10]}\"","typeGuard":"def key_is_mapped(name: str, mapping: dict) -> bool:\n    key = name.split(\".\")[-2]\n    return key in mapping","tryCatchPattern":"try:\n    main(hf_ckpt_path, save_path, n_experts, mp)\nexcept AssertionError as e:\n    if \"not found in mapping\" in str(e):\n        raise SystemExit(\n            \"Checkpoint naming differs from expected HF DeepSeek-V3 layout. \"\n            \"Inspect the key in the message and extend `mapping` in convert.py.\"\n        )\n    raise","preventionTips":["Only convert checkpoints with the exact HF naming this script targets","Dry-run the key rename over all safetensors keys before a long conversion","When HF releases new model revisions, diff tensor names first: safetensors safe_open keys vs mapping"],"tags":["checkpoint-conversion","safetensors","huggingface","key-mapping","deepseek"],"backgroundTag":null,"analyzedSha":"9b4e9788e4a3a731f7567338ed15d3ec549ce03b","analyzedAt":"2026-08-14T19:02:32.748Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}