{"record":{"id":"733468148de0efc9","repo":"invoke-ai/InvokeAI","slug":"unexpected-key-k","errorCode":null,"errorMessage":"Unexpected key: {k}","messagePattern":"Unexpected key: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/flux/ip_adapter/xlabs_ip_adapter_flux.py","lineNumber":62,"sourceCode":"        )\n        self.ip_adapter_double_blocks = IPAdapterDoubleBlocks(\n            num_double_blocks=params.num_double_blocks, context_dim=params.context_dim, hidden_dim=params.hidden_dim\n        )\n\n    def load_xlabs_state_dict(self, state_dict: dict[str, torch.Tensor], assign: bool = False):\n        \"\"\"We need this custom function to load state dicts rather than using .load_state_dict(...) because the model\n        structure does not match the state_dict structure.\n        \"\"\"\n        # Split the state_dict into the image projection model and the double blocks.\n        image_proj_sd: dict[str, torch.Tensor] = {}\n        double_blocks_sd: dict[str, torch.Tensor] = {}\n        for k, v in state_dict.items():\n            if k.startswith(\"ip_adapter_proj_model.\"):\n                image_proj_sd[k] = v\n            elif k.startswith(\"double_blocks.\"):\n                double_blocks_sd[k] = v\n            else:\n                raise ValueError(f\"Unexpected key: {k}\")\n\n        # Initialize the image projection model.\n        image_proj_sd = {k.replace(\"ip_adapter_proj_model.\", \"\"): v for k, v in image_proj_sd.items()}\n        self.image_proj.load_state_dict(image_proj_sd, assign=assign)\n\n        # Initialize the double blocks.\n        double_blocks_sd = {k.replace(\"processor.\", \"\"): v for k, v in double_blocks_sd.items()}\n        self.ip_adapter_double_blocks.load_state_dict(double_blocks_sd, assign=assign)\n","sourceCodeStart":44,"sourceCodeEnd":71,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/ip_adapter/xlabs_ip_adapter_flux.py#L44-L71","documentation":"load_xlabs_state_dict partitions an XLabs IP-Adapter checkpoint into an image-projection dict (keys starting with 'ip_adapter_proj_model.') and a double-blocks dict (keys starting with 'double_blocks.'), loading each into the corresponding submodules. Any key with another prefix cannot belong to an XLabs Flux IP-Adapter checkpoint (e.g. a diffusers-format or CLIP-vision key), so it raises instead of silently dropping weights.","triggerScenarios":"Calling load_xlabs_state_dict with a state_dict containing keys outside the two expected prefixes — e.g. loading a diffusers IP-Adapter checkpoint (keys like 'image_proj.', 'ip_adapter.'), a transformer-suffixed key, or an unrelated tensor accidentally merged in.","commonSituations":"Pointing the loader at the wrong checkpoint file (diffusers-format XLabs adapter vs InvokeAI-format); checkpoint saved with extra wrapper prefixes; mixing adapter formats across versions.","solutions":["Use an XLabs-format IP-Adapter Flux checkpoint whose keys all start with 'ip_adapter_proj_model.' or 'double_blocks.'.","Convert/strip foreign prefixes before calling, e.g. map diffusers keys to the XLabs naming scheme.","Print sorted(state_dict.keys())[:10] to identify the unexpected prefix and adjust key-mapping code accordingly.","If intentional extra keys are present, filter them out before passing: sd = {k:v for k,v in sd.items() if k.startswith(('ip_adapter_proj_model.','double_blocks.'))}"],"exampleFix":"// before\nmodel.load_xlabs_state_dict(state_dict, assign=True)  # state_dict has 'image_proj.xxx' keys\n// after\nrenamed = {k.replace(\"image_proj.\", \"ip_adapter_proj_model.\"): v for k, v in state_dict.items()}\nmodel.load_xlabs_state_dict(renamed, assign=True)","handlingStrategy":"validation","validationCode":"bad = [k for k in state_dict if not k.startswith((\"ip_adapter_proj_model.\", \"double_blocks.\"))]\nif bad:\n    raise ValueError(f\"non-XLabs keys present: {bad[:5]} ...; convert the checkpoint first\")","typeGuard":"def is_xlabs_ip_adapter_state_dict(sd: dict) -> bool:\n    return all(k.startswith((\"ip_adapter_proj_model.\", \"double_blocks.\")) for k in sd)","tryCatchPattern":"try:\n    model.load_xlabs_state_dict(state_dict, assign=assign)\nexcept ValueError as e:\n    if \"Unexpected key\" in str(e):\n        raise RuntimeError(f\"checkpoint is not XLabs-format; offending keys: \"\n                           f\"{[k for k in state_dict if not k.startswith(('ip_adapter_proj_model.','double_blocks.'))][:5]}\") from e\n    raise","preventionTips":["Confirm the checkpoint is the XLabs (not diffusers) IP-Adapter Flux format before loading.","Preview key prefixes with itertools.islice(sorted(state_dict), 5) when integrating new checkpoints.","Keep a key-mapping/convert step for foreign formats and filter out irrelevant tensors before load."],"tags":["state-dict","checkpoint","ip-adapter","key-mismatch"],"backgroundTag":"unexpected-state-dict-key","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}