invoke-ai/InvokeAI · error · RuntimeError

Unable to decipher Load Class based on given config.json

Error message

Unable to decipher Load Class based on given config.json

What it means

get_hf_load_class reads the model's config.json to decide which diffusers or transformers class instantiates the model. If the config has neither a `_class_name` nor an `architectures` key, the loader cannot determine the class and raises this RuntimeError. It is a guard against loading models whose configuration is incomplete or not in a recognizable diffusers/transformers layout.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/generic_diffusers.py:72

    def get_hf_load_class(self, model_path: Path, submodel_type: Optional[SubModelType] = None) -> ModelMixin:
        """Given the model path and submodel, returns the diffusers ModelMixin subclass needed to load."""
        result = None
        if submodel_type:
            try:
                config = self._load_diffusers_config(model_path, config_name="model_index.json")
                module, class_name = config[submodel_type.value]
                result = self._hf_definition_to_type(module=module, class_name=class_name)
            except KeyError as e:
                raise ValueError(f'The "{submodel_type}" submodel is not available for this model.') from e
        else:
            try:
                config = self._load_diffusers_config(model_path, config_name="config.json")
                if class_name := config.get("_class_name"):
                    result = self._hf_definition_to_type(module="diffusers", class_name=class_name)
                elif class_name := config.get("architectures"):
                    result = self._hf_definition_to_type(module="transformers", class_name=class_name[0])
                else:
                    raise RuntimeError("Unable to decipher Load Class based on given config.json")
            except KeyError as e:
                raise ValueError("An expected config.json file is missing from this model.") from e
        assert result is not None
        return result

    # TO DO: Add exception handling
    def _hf_definition_to_type(self, module: str, class_name: str) -> ModelMixin:  # fix with correct type
        if module in [
            "diffusers",
            "transformers",
            "invokeai.backend.quantization.fast_quantized_transformers_model",
            "invokeai.backend.quantization.fast_quantized_diffusion_model",
        ]:
            res_type = sys.modules[module]
        else:
            res_type = sys.modules["diffusers"].pipelines
        result: ModelMixin = getattr(res_type, class_name)
        return result

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Open the model's config.json and add the `_class_name` field (e.g. "_class_name": "UNet2DConditionModel") matching the actual architecture.
2. For transformers-based models, add an `architectures` array (e.g. "architectures": ["CLIPTextModel"]).
3. Re-download or re-export the model from the original HuggingFace repo so config.json is complete.
4. Verify you are pointing the loader at the subfolder that actually contains the full config, not a parent directory.

Example fix

// before (config.json fragment)
{ "model_type": "unet", "sample_size": 64 }
// after
{ "_class_name": "UNet2DConditionModel", "model_type": "unet", "sample_size": 64 }

import json
cfg = json.loads((model_path / "config.json").read_text())
if "_class_name" not in cfg and "architectures" not in cfg:
    raise ValueError(f"config.json has no _class_name or architectures: {model_path}")

def has_load_class(cfg: dict) -> bool:
    return isinstance(cfg, dict) and bool(cfg.get("_class_name") or cfg.get("architectures"))

try:
    cls = loader.get_hf_load_class(model_path)
except RuntimeError as e:
    if "Unable to decipher Load Class" in str(e):
        fix_config_json(model_path)  # add _class_name/architectures
    else:
        raise

When it happens

Trigger: Calling get_hf_load_class (directly or via diffusers_load_directory/_load_model) on a model directory whose config.json lacks both `_class_name` and `architectures` fields.

Common situations: Hand-converted or partially downloaded models with a stub config.json; single-file checkpoints converted with custom scripts that omit metadata keys; non-diffusers model formats that ship a config.json without HuggingFace metadata.

Related errors

• To extract the VAE and Qwen3-VL encoder, the {model_name} mo
• An expected config.json file is missing from this model.
• Expected Main_Diffusers_Ideogram4_Config, got {type(config).
• CheckpointConfigBase is not implemented for Qwen Image Edit
• Only Qwen3Encoder_SDNQ_Config or Qwen3Encoder_SDNQ_Folder_Co

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