{"record":{"id":"0861d193b877e301","repo":"huggingface/pytorch-image-models","slug":"patch-embedding-shape-mismatch-in-checkpoint-path","errorCode":null,"errorMessage":"Patch embedding shape mismatch in {checkpoint_path}: checkpoint={tuple(embed_w.shape)}, model={tuple(embeds.proj.weight.shape)}","messagePattern":"Patch embedding shape mismatch in (.+?): checkpoint=(.+?), model=(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"timm/models/vision_transformer.py","lineNumber":1530,"sourceCode":"            embed_conv_w = adapt_input_conv(embeds.in_chans, embed_conv_w)\n            if embed_conv_w.shape[-2:] != embeds.patch_size:\n                embed_conv_w = resample_patch_embed(\n                    embed_conv_w,\n                    embeds.patch_size,\n                    interpolation=interpolation,\n                    antialias=antialias,\n                    verbose=True,\n                )\n            if embeds.is_linear:\n                if embeds.channels_last:\n                    embed_w = embed_conv_w.permute(0, 2, 3, 1).flatten(1)\n                else:\n                    embed_w = embed_conv_w.flatten(1)\n            else:\n                embed_w = embed_conv_w\n\n        if embed_w.shape != embeds.proj.weight.shape:\n            raise ValueError(\n                f'Patch embedding shape mismatch in {checkpoint_path}: '\n                f'checkpoint={tuple(embed_w.shape)}, model={tuple(embeds.proj.weight.shape)}')\n        embeds.proj.weight.copy_(embed_w)\n        if embeds.proj.bias is not None and f'{prefix}embedding/bias' in w:\n            embeds.proj.bias.copy_(_n2p(w[f'{prefix}embedding/bias']))\n\n        if embeds.cls_token is not None and f'{prefix}cls' in w:\n            embeds.cls_token.copy_(_n2p(w[f'{prefix}cls'], t=False))\n\n        pos_embed_key = (\n            f'{prefix}pos_embedding' if big_vision\n            else f'{prefix}Transformer/posembed_input/pos_embedding')\n        if embeds.pos_embed is not None and pos_embed_key in w:\n            pos_embed_w = _n2p(w[pos_embed_key], t=False)\n            prefix_pos_embed = None\n            if pos_embed_w.ndim == 2:\n                pos_embed_w = pos_embed_w.unsqueeze(0)\n            if pos_embed_w.ndim == 3:","sourceCodeStart":1512,"sourceCodeEnd":1548,"githubUrl":"https://github.com/huggingface/pytorch-image-models/blob/9a5261e31b3b5128526eb2658333b4c0a54464ae/timm/models/vision_transformer.py#L1512-L1548","documentation":"After conversion and optional resampling, the checkpoint patch-embedding weight must exactly match the model's embeds.proj.weight shape. A remaining mismatch (e.g. different embed dim or channel count) is fatal.","triggerScenarios":"Loading a JAX ViT checkpoint into a model with a different embed_dim, in_chans that adapt_input_conv cannot reconcile, or a patch size that resample_patch_embed did not adjust.","commonSituations":"Loading checkpoints into a renamed/modified architecture, or mismatched variant names (base weights into large model).","solutions":["Ensure the model variant matches the checkpoint (same embed_dim and patch_size)","Set in_chans=3 (or let adapt_input_conv adapt) and confirm the checkpoint stores standard channels","If intentional, load with strict=False outside this JAX path or pre-transform the weights to the target shape"],"exampleFix":"# before\nmodel = vision_transformer.vit_base_patch16_224()\nload_pretrained(model, 'vit_large.npz')\n# after\nmodel = vision_transformer.vit_large_patch16_224()\nload_pretrained(model, 'vit_large.npz')","handlingStrategy":"validation","validationCode":"ew = w['embedding/kernel'].reshape(-1) if w['embedding/kernel'].ndim == 4 else w['embedding/kernel']\nassert tuple(ew.shape) == tuple(model.patch_embed.proj.weight.shape), 'shape mismatch'","typeGuard":null,"tryCatchPattern":"try:\n    load_pretrained(model, path)\nexcept ValueError as e:\n    if 'Patch embedding shape mismatch' in str(e):\n        log.warning('variant/checkpoint mismatch; skipping patch embed load')\n    else:\n        raise","preventionTips":["Match model variant and patch_size to checkpoint before loading","Print expected vs checkpoint shapes in debug logs"],"tags":["timm","vit","checkpoint","shape-mismatch"],"backgroundTag":"checkpoint-weight-mismatch","analyzedSha":"9a5261e31b3b5128526eb2658333b4c0a54464ae","analyzedAt":"2026-08-27T02:34:25.417Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}