invoke-ai/InvokeAI · error · RuntimeError

Failed to load Qwen VL tokenizer. Single-file Qwen VL encode

Error message

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}

What it means

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.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/qwen_image.py:377

    def _load_tokenizer_with_offline_fallback(self) -> AnyModel:
        from transformers import AutoTokenizer

        from invokeai.backend.util.logging import InvokeAILogger

        logger = InvokeAILogger.get_logger(self.__class__.__name__)

        try:
            return AutoTokenizer.from_pretrained(self.DEFAULT_HF_REPO, local_files_only=True)
        except OSError:
            logger.info(
                f"Tokenizer for single-file Qwen VL encoder not found in HuggingFace cache; "
                f"downloading from {self.DEFAULT_HF_REPO} (one-time, requires network access)."
            )
            try:
                return AutoTokenizer.from_pretrained(self.DEFAULT_HF_REPO)
            except OSError as e:
                raise RuntimeError(
                    f"Failed to load Qwen VL tokenizer. Single-file Qwen VL encoder checkpoints do not "
                    f"include the tokenizer; it must be downloaded from HuggingFace ({self.DEFAULT_HF_REPO}) "
                    f"on first use. Either restore network access, or install the encoder in the "
                    f"diffusers folder layout (text_encoder/ + tokenizer/) instead. Original error: {e}"
                ) from e

    def _load_text_encoder_from_singlefile(self, config: QwenVLEncoder_Checkpoint_Config) -> AnyModel:
        from safetensors.torch import load_file
        from transformers import AutoConfig, Qwen2_5_VLForConditionalGeneration

        from invokeai.backend.util.logging import InvokeAILogger

        logger = InvokeAILogger.get_logger(self.__class__.__name__)

        model_path = Path(config.path)

        target_device = TorchDevice.choose_torch_device()
        model_dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. 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.
2. Reinstall the model in diffusers folder layout (text_encoder/ + tokenizer/ directories) so the tokenizer ships with the model.
3. Manually download the Qwen/Qwen2.5-VL-7B-Instruct tokenizer files and place them in the HF cache, then retry.

Example fix

# before: single-file encoder, offline -> RuntimeError
# after: diffusers layout
models/qwen_image/
  text_encoder/
  tokenizer/   # contains tokenizer.json, tokenizer_config.json, vocab.json, merges.txt

import os
if os.environ.get("HF_HUB_OFFLINE") == "1" or not has_network("huggingface.co"):
    logger.warning("Offline: tokenizer must already be in HF cache or use diffusers folder layout")

try:
    tok = loader.load_model(config, submodel_type=SubModelType.Tokenizer)
except RuntimeError as e:
    if "Qwen VL tokenizer" in str(e):
        logger.error("Pre-download tokenizer or switch to diffusers layout: %s", e)
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to load Qwen VL architecture config. Single-file Qwen
• Expected PreTrainedTokenizerBase for Gemma tokenizer, got {t
• Expected PreTrainedTokenizerBase for tokenizer, got {type(to
• Tokenizer returned unexpected types.
• Blend is not supported here - you need to get tokens for eac

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/10ee1d8c0eeac174. Report an issue: GitHub.