invoke-ai/InvokeAI · error · ValueError

CLIP Embed model config dict must include a 'variant' field

Error message

CLIP Embed model config dict must include a 'variant' field

What it means

CLIP Embed model configs additionally need 'variant' to distinguish model variants in the discriminator tag; when the field is absent entirely, this ValueError is raised by get_model_discriminator_value.

Source

Thrown at invokeai/backend/model_manager/configs/base.py:200

                    base_ = str(base_.value)
                elif not isinstance(base_, str):
                    raise ValueError("Model config dict 'base' field must be a string or Enum")
                tag_strings.append(base_)

            # Special case: CLIP Embed models also need the variant to distinguish them.
            if (
                type_ == ModelType.CLIPEmbed.value
                and format_ == ModelFormat.Diffusers.value
                and base_ == BaseModelType.Any.value
            ):
                if variant_ := v.get("variant"):
                    if isinstance(variant_, Enum):
                        variant_ = variant_.value
                    elif not isinstance(variant_, str):
                        raise ValueError("Model config dict 'variant' field must be a string or Enum")
                    tag_strings.append(variant_)
                else:
                    raise ValueError("CLIP Embed model config dict must include a 'variant' field")

            return ".".join(tag_strings)
        else:
            raise ValueError(
                "Model config discriminator value must be computed from a dict or ModelConfigBase instance"
            )

    @classmethod
    @abstractmethod
    def from_model_on_disk(cls, mod: ModelOnDisk, override_fields: dict[str, Any]) -> Self:
        """Given the model on disk and any override fields, attempt to construct an instance of this config class.

        This method serves to identify whether the model on disk matches this config class, and if so, to extract any
        additional metadata needed to instantiate the config.

        Implementations should raise a NotAMatchError if the model does not match this config class."""
        raise NotImplementedError(f"from_model_on_disk not implemented for {cls.__name__}")

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Add the variant field, e.g. {'variant': CLIPVisionModelVariant.LARGE.value} (typically 'large' or 'huge').
2. Inspect the model's config.json in its diffusers folder to determine the correct variant.
3. If the model is not actually CLIP Embed, correct the 'type'/'format' fields so the special case doesn't apply.

Example fix

// before
{'type': 'clip_embed', 'format': 'diffusers', 'base': 'any'}
// after
{'type': 'clip_embed', 'format': 'diffusers', 'base': 'any', 'variant': 'large'}

def ensure_clip_embed_variant(cfg: dict) -> dict:
    if cfg.get('type') == 'clip_embed' and cfg.get('format') == 'diffusers' and not cfg.get('variant'):
        cfg['variant'] = 'large'  # or read from the model's config.json
    return cfg

def has_required_clip_embed_fields(cfg: dict) -> bool:
    return bool(cfg.get('variant')) if (
        cfg.get('type') == 'clip_embed' and cfg.get('format') == 'diffusers'
    ) else True

try:
    config = AnyModelConfig(**cfg)
except ValueError as e:
    if "must include a 'variant' field" in str(e):
        cfg['variant'] = 'large'
        config = AnyModelConfig(**cfg)
    else:
        raise

When it happens

Trigger: Instantiating a config dict with type='clip_embed', format='diffusers', base='any' but no 'variant' key at all.

Common situations: Importing configs from older InvokeAI versions or third-party tools that omit variant; hand-written dicts missing the field; partial deserialization dropping None/missing keys.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Model config dict 'variant' field must be a string or Enum
• Model config dict 'type' field must be a string or Enum
• Model config dict 'format' field must be a string or Enum
• Model config dict 'base' field must be a string or Enum
• cfg_scale values must be finite.

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