{"record":{"id":"c00736b445fbaaff","repo":"tensorflow/models","slug":"checkpoint-state-dict-is-missing-required-key-hea","errorCode":null,"errorMessage":"Checkpoint state dict is missing required key 'head.weight'.","messagePattern":"Checkpoint state dict is missing required key 'head\\.weight'\\.","errorType":"exception","errorClass":"ClassifierError","httpStatus":null,"severity":"error","filePath":"official/projects/waste_identification_ml/model_inference_with_tracking/sam3_dinov3_tracking_pipeline/dinov3_classifier.py","lineNumber":162,"sourceCode":"    checkpoint_path: Filesystem path to the checkpoint.\n    device: Target device for `map_location`.\n\n  Returns:\n    The `model_state_dict` mapping from parameter name to tensor.\n\n  Raises:\n    ClassifierError: If the checkpoint is missing required keys.\n  \"\"\"\n  checkpoint = torch.load(\n      checkpoint_path, map_location=device, weights_only=True\n  )\n  if \"model_state_dict\" not in checkpoint:\n    raise ClassifierError(\n        \"Checkpoint is missing required key 'model_state_dict'.\"\n    )\n  saved_state_dict = checkpoint[\"model_state_dict\"]\n  if \"head.weight\" not in saved_state_dict:\n    raise ClassifierError(\n        \"Checkpoint state dict is missing required key 'head.weight'.\"\n    )\n  return saved_state_dict\n\n\ndef _build_image_transform(config: config_loader.DINOv3Config) -> v2.Compose:\n  \"\"\"Builds the preprocessing pipeline used to feed PIL images to the model.\n\n  Args:\n    config: DINOv3 model configuration providing image size and normalization\n      statistics.\n\n  Returns:\n    A torchvision v2.Compose pipeline.\n  \"\"\"\n  return v2.Compose([\n      v2.ToImage(),\n      v2.Resize(","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/tensorflow/models/blob/e006f5f0d534913e49c1f1dae87364039fa607e2/official/projects/waste_identification_ml/model_inference_with_tracking/sam3_dinov3_tracking_pipeline/dinov3_classifier.py#L144-L180","documentation":"Schema check in _load_checkpoint_state_dict: model_state_dict was found, but its 'head.weight' tensor is missing. The classifier needs the final linear head's weight matrix both to infer the pooling strategy (from its input feature dimension) and to restore predictions; without it the checkpoint cannot reconstruct the classifier, so loading aborts. Typically a backbone-only checkpoint or a state dict filtered to encoder keys.","triggerScenarios":"Thrown at official/projects/waste_identification_ml/model_inference_with_tracking/sam3_dinov3_tracking_pipeline/dinov3_classifier.py:162 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Use the fine-tuned checkpoint that includes the classification head, not backbone-only weights","If the head was stripped, re-finetune or re-attach a head and re-save the checkpoint","Inspect checkpoint['model_state_dict'].keys() to confirm 'head.weight' exists"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"e006f5f0d534913e49c1f1dae87364039fa607e2","analyzedAt":"2026-08-24T14:09:15.576Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}