{"record":{"id":"4d57f328cb34325e","repo":"invoke-ai/InvokeAI","slug":"expected-a-safetensors-file-got-mod-path-suffix-4d57f3","errorCode":null,"errorMessage":"expected a .safetensors file, got {mod.path.suffix or '(no suffix)'}","messagePattern":"expected a \\.safetensors file, got (.+?)","errorType":"validation","errorClass":"NotAMatchError","httpStatus":null,"severity":"warning","filePath":"invokeai/backend/model_manager/configs/qwen_vl_encoder.py","lineNumber":142,"sourceCode":"\n    The matching tokenizer + processor are pulled from HuggingFace\n    (`Qwen/Qwen2.5-VL-7B-Instruct`) on first use and cached for offline use.\n    \"\"\"\n\n    base: Literal[BaseModelType.Any] = Field(default=BaseModelType.Any)\n    type: Literal[ModelType.QwenVLEncoder] = Field(default=ModelType.QwenVLEncoder)\n    format: Literal[ModelFormat.Checkpoint] = Field(default=ModelFormat.Checkpoint)\n\n    @classmethod\n    def from_model_on_disk(cls, mod: ModelOnDisk, override_fields: dict[str, Any]) -> Self:\n        raise_if_not_file(mod)\n\n        raise_for_override_fields(cls, override_fields)\n\n        # Only safetensors checkpoints are supported as single-file Qwen VL encoders.\n        # Reject other extensions cheaply before attempting to read keys.\n        if mod.path.suffix != \".safetensors\":\n            raise NotAMatchError(f\"expected a .safetensors file, got {mod.path.suffix or '(no suffix)'}\")\n\n        # Read only the key index — a 7GB fp8 encoder weighs ~7GB on disk, but we\n        # only need the key names to classify it, not the tensor data.\n        try:\n            keys = _read_safetensors_keys(mod.path)\n        except Exception as e:\n            raise NotAMatchError(f\"could not read safetensors header: {e}\") from e\n\n        if not _has_qwen_vl_keys(keys):\n            raise NotAMatchError(\"state dict does not look like a Qwen2.5-VL/Qwen2-VL checkpoint\")\n\n        return cls(**override_fields)\n","sourceCodeStart":124,"sourceCodeEnd":155,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/qwen_vl_encoder.py#L124-L155","documentation":"`NotAMatchError` from the single-file branch of `QwenVLTextEncoderConfig.from_model_on_disk`: the candidate file is not a `.safetensors` file, so the loader rejects it before reading any keys. Only safetensors checkpoints are supported for single-file Qwen VL encoders; other extensions (`.bin`, `.pt`, `.ckpt`, no suffix) cannot be inspected cheaply or safely.","triggerScenarios":"Installing a single-file Qwen VL encoder whose `ModelOnDisk.path` suffix is not `.safetensors` — e.g. a PyTorch `.bin`/`.pt` checkpoint, an archive, or a directory-less file with no extension.","commonSituations":"Old-style torch pickle checkpoints, config files placed at the model root and probed as weights, renamed downloads that lost the extension, GGUF or fp8 files with custom extensions.","solutions":["Convert the checkpoint to safetensors (e.g. via `safetensors.torch.save_file` or a conversion script) and install the `.safetensors` file","Download the safetensors variant from the model repo instead of the `.bin` variant","Ensure the file keeps its `.safetensors` extension (don't strip it when renaming)","If the path is actually a directory-based model, let the folder-branch of the config handle it instead of pointing at a loose file"],"exampleFix":"// before\nmv model.bin qwen_encoder.safetensors   # wrong: just renaming\n// after\npython -c \"from safetensors.torch import load_file,save_file; ...\"  # actually convert, keep .safetensors","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef is_safetensors_file(path: Path) -> bool:\n    return path.is_file() and path.suffix == \".safetensors\"","typeGuard":"def is_single_file_safetensors(mod_path: Path) -> bool:\n    return mod_path.is_file() and mod_path.suffix == \".safetensors\"","tryCatchPattern":"try:\n    cfg = QwenVLTextEncoderConfig.from_model_on_disk(mod, override_fields)\nexcept NotAMatchError as e:\n    if \"expected a .safetensors file\" in str(e):\n        print(\"Convert or re-download the checkpoint in safetensors format\")\n    raise","preventionTips":["Prefer safetensors downloads over .bin/.pt when a repo offers both","Never strip the .safetensors extension when renaming model files","Convert pickle checkpoints to safetensors before importing"],"tags":["safetensors","model-format","qwen-vl"],"backgroundTag":"unsupported-model-format","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}