{"record":{"id":"eeb30a37561ebb46","repo":"invoke-ai/InvokeAI","slug":"a-submodel-type-must-be-provided-when-loading-main","errorCode":null,"errorMessage":"A submodel type must be provided when loading main pipelines.","messagePattern":"A submodel type must be provided when loading main pipelines\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/flux.py","lineNumber":1595,"sourceCode":"        logger.debug(\n            \"[SDNQ] FluxSDNQDiffusersModel._load_model called with config=%s, submodel=%s\",\n            type(config).__name__,\n            submodel_type,\n        )\n        # Handle single-file SDNQ checkpoint (Main_SDNQ_FLUX_Config)\n        if isinstance(config, Main_SDNQ_FLUX_Config):\n            if submodel_type == SubModelType.Transformer:\n                return self._load_sdnq_transformer_checkpoint(config)\n            raise ValueError(\n                f\"Only Transformer submodels are supported for checkpoint format. Received: {submodel_type}\"\n            )\n\n        # Handle diffusers-format SDNQ model (Main_SDNQ_Diffusers_FLUX_Config)\n        if not isinstance(config, Main_SDNQ_Diffusers_FLUX_Config):\n            raise ValueError(f\"Expected Main_SDNQ_Diffusers_FLUX_Config, got {type(config).__name__}\")\n\n        if submodel_type is None:\n            raise ValueError(\"A submodel type must be provided when loading main pipelines.\")\n\n        # Prefer the path discovery actually found. `model_index.json` names its components with\n        # arbitrary keys, and identification records the key it saw — but reconstructing\n        # `model_path / submodel_type.value` here assumes the key always equals the slot name. A\n        # pipeline whose index calls its CLIP encoder something else is then discovered fine and\n        # loaded from a folder that does not exist. Fall back to the conventional name when a config\n        # predates submodel discovery.\n        model_path = Path(config.path)\n        submodel_path = resolve_submodel_path(config, submodel_type, model_path / submodel_type.value)\n\n        # These branches build their modules by hand (`init_empty_weights` + `load_state_dict`)\n        # rather than through `from_pretrained`, so they arrive in training mode — `put_in_eval_mode`\n        # in `load_default._load_and_cache` is what puts every loaded model into inference mode.\n        match submodel_type:\n            case SubModelType.Transformer:\n                return self._load_sdnq_transformer(submodel_path, config)\n            case SubModelType.TextEncoder:\n                return self._load_text_encoder(submodel_path)","sourceCodeStart":1577,"sourceCodeEnd":1613,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/flux.py#L1577-L1613","documentation":"When loading an SDNQ diffusers FLUX main pipeline, the caller must say which component (submodel) to load. A None submodel_type is ambiguous for a multi-component pipeline, so _load_model raises ValueError demanding a submodel type.","triggerScenarios":"Calling the SDNQ diffusers loader's _load_model (or load_model through the registry) with submodel_type=None for a Main_SDNQ_Diffusers_FLUX_Config.","commonSituations":"Scripts that load main models without specifying a submodel, which works for checkpoint formats but not diffusers pipelines; default arguments left unset in custom orchestration code.","solutions":["Pass an explicit SubModelType (Transformer, VAE, Tokenizer, Tokenizer2, TextEncoder, TextEncoder2) when loading a diffusers main model.","For full-pipeline loading, iterate over the pipeline's components and load each with its own submodel type.","Guard calls so submodel_type defaults to SubModelType.Transformer when omitted."],"exampleFix":"// before\nmodel = loader.load_model(sdnq_diffusers_config, None)\n// after\nsub = submodel_type or SubModelType.Transformer\nmodel = loader.load_model(sdnq_diffusers_config, sub)","handlingStrategy":"validation","validationCode":"if submodel_type is None:\n    raise ValueError(\"Pass an explicit SubModelType (e.g. SubModelType.Transformer) when loading SDNQ diffusers pipelines\")","typeGuard":"def has_submodel(submodel_type: Optional[SubModelType]) -> bool:\n    return submodel_type is not None","tryCatchPattern":"try:\n    model = loader.load_model(config, submodel_type)\nexcept ValueError as e:\n    if \"submodel type must be provided\" in str(e):\n        model = loader.load_model(config, SubModelType.Transformer)\n    else:\n        raise","preventionTips":["Always pass submodel_type when loading diffusers main models","Default to SubModelType.Transformer for main checkpoints in helper code","Don't reuse loading code written for single-file (submodel-less) formats"],"tags":["submodel","sdnq","argument-validation"],"backgroundTag":"missing-required-argument","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}