{"record":{"id":"10ee1d8c0eeac174","repo":"invoke-ai/InvokeAI","slug":"failed-to-load-qwen-vl-tokenizer-single-file-qwen","errorCode":null,"errorMessage":"Failed to load Qwen VL tokenizer. Single-file Qwen VL encoder checkpoints do not include the tokenizer; it must be downloaded from HuggingFace (Qwen/Qwen2.5-VL-7B-Instruct) on first use. Either restore network access, or install the encoder in the diffusers folder layout (text_encoder/ + tokenizer/) instead. Original error: {e}","messagePattern":"Failed to load Qwen VL tokenizer\\. Single-file Qwen VL encoder checkpoints do not include the tokenizer; it must be downloaded from HuggingFace \\(Qwen/Qwen2\\.5-VL-7B-Instruct\\) on first use\\. Either restore network access, or install the encoder in the diffusers folder layout \\(text_encoder/ \\+ tokenizer/\\) instead\\. Original error: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/qwen_image.py","lineNumber":377,"sourceCode":"\n    def _load_tokenizer_with_offline_fallback(self) -> AnyModel:\n        from transformers import AutoTokenizer\n\n        from invokeai.backend.util.logging import InvokeAILogger\n\n        logger = InvokeAILogger.get_logger(self.__class__.__name__)\n\n        try:\n            return AutoTokenizer.from_pretrained(self.DEFAULT_HF_REPO, local_files_only=True)\n        except OSError:\n            logger.info(\n                f\"Tokenizer for single-file Qwen VL encoder not found in HuggingFace cache; \"\n                f\"downloading from {self.DEFAULT_HF_REPO} (one-time, requires network access).\"\n            )\n            try:\n                return AutoTokenizer.from_pretrained(self.DEFAULT_HF_REPO)\n            except OSError as e:\n                raise RuntimeError(\n                    f\"Failed to load Qwen VL tokenizer. Single-file Qwen VL encoder checkpoints do not \"\n                    f\"include the tokenizer; it must be downloaded from HuggingFace ({self.DEFAULT_HF_REPO}) \"\n                    f\"on first use. Either restore network access, or install the encoder in the \"\n                    f\"diffusers folder layout (text_encoder/ + tokenizer/) instead. Original error: {e}\"\n                ) from e\n\n    def _load_text_encoder_from_singlefile(self, config: QwenVLEncoder_Checkpoint_Config) -> AnyModel:\n        from safetensors.torch import load_file\n        from transformers import AutoConfig, Qwen2_5_VLForConditionalGeneration\n\n        from invokeai.backend.util.logging import InvokeAILogger\n\n        logger = InvokeAILogger.get_logger(self.__class__.__name__)\n\n        model_path = Path(config.path)\n\n        target_device = TorchDevice.choose_torch_device()\n        model_dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/qwen_image.py#L359-L395","documentation":"A single-file Qwen VL text-encoder checkpoint contains only the encoder weights, not the tokenizer. InvokeAI tries to fetch the tokenizer from HuggingFace (Qwen/Qwen2.5-VL-7B-Instruct) and caches it; if AutoTokenizer.from_pretrained fails with an OSError (no network, HF hub unreachable), it wraps it in this RuntimeError. The error explicitly tells you the two supported remedies.","triggerScenarios":"Loading a single-file Qwen VL encoder with submodel_type=Tokenizer while the tokenizer is absent from the HF cache and the machine is offline or blocked from huggingface.co.","commonSituations":"Air-gapped/CI machines; HF_HUB_OFFLINE set or huggingface.co unreachable; first-time use of a single-file .safetensors Qwen encoder; firewall/proxy blocking the HF download.","solutions":["Restore network access (or unset HF_HUB_OFFLINE / configure proxy) so AutoTokenizer.from_pretrained('Qwen/Qwen2.5-VL-7B-Instruct') can download once; it is cached afterwards.","Reinstall the model in diffusers folder layout (text_encoder/ + tokenizer/ directories) so the tokenizer ships with the model.","Manually download the Qwen/Qwen2.5-VL-7B-Instruct tokenizer files and place them in the HF cache, then retry."],"exampleFix":"# before: single-file encoder, offline -> RuntimeError\n# after: diffusers layout\nmodels/qwen_image/\n  text_encoder/\n  tokenizer/   # contains tokenizer.json, tokenizer_config.json, vocab.json, merges.txt","handlingStrategy":"try-catch","validationCode":"import os\nif os.environ.get(\"HF_HUB_OFFLINE\") == \"1\" or not has_network(\"huggingface.co\"):\n    logger.warning(\"Offline: tokenizer must already be in HF cache or use diffusers folder layout\")","typeGuard":null,"tryCatchPattern":"try:\n    tok = loader.load_model(config, submodel_type=SubModelType.Tokenizer)\nexcept RuntimeError as e:\n    if \"Qwen VL tokenizer\" in str(e):\n        logger.error(\"Pre-download tokenizer or switch to diffusers layout: %s\", e)\n    raise","preventionTips":["Pre-download the tokenizer once while online: AutoTokenizer.from_pretrained('Qwen/Qwen2.5-VL-7B-Instruct').","Install single-file Qwen encoders in diffusers layout (text_encoder/ + tokenizer/).","Pre-warm HF cache on air-gapped deployments by mirroring the repo."],"tags":["network","tokenizer","huggingface","offline"],"backgroundTag":"hf-model-download-failed","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}