{"record":{"id":"9410abe3d6294f7e","repo":"invoke-ai/InvokeAI","slug":"cannot-split-qkv-tensor-key-first-dimension","errorCode":null,"errorMessage":"Cannot split QKV tensor '{key}': first dimension ({tensor.shape[0]}) is not divisible by 3. The model file may be corrupted or incompatible.","messagePattern":"Cannot split QKV tensor '(.+?)': first dimension \\((.+?)\\) is not divisible by 3\\. The model file may be corrupted or incompatible\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":110,"sourceCode":"            continue\n\n        # Handle fused QKV weights - need to split\n        if \".attention.qkv.\" in key:\n            # Get the layer prefix and suffix\n            prefix = key.rsplit(\".attention.qkv.\", 1)[0]\n            suffix = key.rsplit(\".attention.qkv.\", 1)[1]  # \"weight\" or \"bias\"\n\n            # Skip non-weight/bias tensors (e.g., FP8 scale_weight tensors)\n            # These are quantization metadata and should not be split\n            if suffix not in (\"weight\", \"bias\"):\n                new_sd[key] = value\n                continue\n\n            # Split the fused QKV tensor into Q, K, V\n            tensor = value\n            if hasattr(tensor, \"shape\"):\n                if tensor.shape[0] % 3 != 0:\n                    raise ValueError(\n                        f\"Cannot split QKV tensor '{key}': first dimension ({tensor.shape[0]}) \"\n                        \"is not divisible by 3. The model file may be corrupted or incompatible.\"\n                    )\n                dim = tensor.shape[0] // 3\n                q = tensor[:dim]\n                k = tensor[dim : 2 * dim]\n                v = tensor[2 * dim :]\n\n                new_sd[f\"{prefix}.attention.to_q.{suffix}\"] = q\n                new_sd[f\"{prefix}.attention.to_k.{suffix}\"] = k\n                new_sd[f\"{prefix}.attention.to_v.{suffix}\"] = v\n            continue\n\n        # Handle attention key renaming\n        if \".attention.\" in key:\n            new_key = key.replace(\".q_norm.\", \".norm_q.\")\n            new_key = new_key.replace(\".k_norm.\", \".norm_k.\")\n            new_key = new_key.replace(\".attention.out.\", \".attention.to_out.0.\")","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L92-L128","documentation":"_convert_z_image_gguf_to_diffusers splits fused attention QKV tensors into separate Q, K, V by dividing the first dimension into three equal parts. If tensor.shape[0] is not divisible by 3 the tensor cannot be a valid fused QKV weight, so the loader raises ValueError rather than producing a silently wrong model. This almost always means the source file is not the expected format rather than a code bug.","triggerScenarios":"Loading a Z-Image single-file/GGUF checkpoint via _load_from_singlefile (or the SDNQ path via _load_sdnq_transformer) where a tensor whose key was classified as fused-QKV has first dim % 3 != 0.","commonSituations":"Truncated or partially downloaded GGUF/single-file checkpoint; wrong architecture file fed to the Z-Image loader (a non-QKV tensor matching the QKV key pattern); checkpoint produced by a different quantization/export tool with differently shaped weights.","solutions":["Re-download the model file and verify its checksum/size; corruption during download is the most common cause.","Confirm the file is actually a Z-Image checkpoint and matches the loader's expected key layout; use the correct loader for other architectures.","Open the checkpoint locally and inspect the tensor named in the message to see its true shape and key prefix.","Update InvokeAI / the loader in case a new checkpoint variant changed the QKV key-matching heuristic."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import os\nexpected = 3 * head_count * head_dim\nshape0 = tensor.shape[0] if hasattr(tensor, \"shape\") else None\nif shape0 is not None and shape0 % 3 != 0:\n    raise ValueError(f\"tensor '{key}' has shape0={shape0}, not a valid fused QKV (expected multiple of 3, e.g. {expected})\")\nif os.path.getsize(model_path) < expected_min_size:\n    raise ValueError(f\"{model_path} looks truncated; re-download it\")","typeGuard":"def is_splittable_qkv(tensor, key: str) -> bool:\n    return hasattr(tensor, \"shape\") and \"qkv\" in key.lower() and tensor.ndim >= 1 and tensor.shape[0] % 3 == 0","tryCatchPattern":"try:\n    model = loader.load_model(config)\nexcept ValueError as e:\n    if \"not divisible by 3\" in str(e):\n        raise RuntimeError(\n            f\"Z-Image checkpoint is corrupted or incompatible ({e}); re-download and verify the checksum\"\n        ) from e\n    raise","preventionTips":["Verify file size/checksum after downloading GGUF or single-file Z-Image checkpoints.","Only feed Z-Image checkpoints to the Z-Image loader; check architecture metadata before loading.","Keep InvokeAI updated so newer checkpoint export variants with changed key layouts are handled.","Inspect suspicious tensors with safetensors/gguf readers before attempting conversion."],"tags":["python","gguf","model-loading","corrupt-file","tensor-shape"],"backgroundTag":"model-checkpoint-corrupted","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}