invoke-ai/InvokeAI · error · ValueError

Model config dict 'variant' field must be a string or Enum

Error message

Model config dict 'variant' field must be a string or Enum

What it means

For CLIP Embed models (type=clip_embed, format=diffusers, base=any), the discriminator also requires a 'variant' string/Enum field; a non-str/non-Enum variant raises ValueError during discriminator computation.

Source

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

            if base_ := v.get("base"):
                if isinstance(base_, Enum):
                    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.

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Pass a string variant (or CLIPVisionModelVariant Enum member), e.g. 'large' / CLIPVisionModelVariant.LARGE.
2. Fix the deserializer to convert variant enums with .value.
3. Drop the field only if this is not actually a CLIP Embed model - check type/format/base.

Example fix

// before
{'type': 'clip_embed', 'format': 'diffusers', 'base': 'any', 'variant': 1}
// after
{'type': 'clip_embed', 'format': 'diffusers', 'base': 'any', 'variant': CLIPVisionModelVariant.LARGE.value}

def normalize_variant(v) -> str:
    return v.value if isinstance(v, Enum) else str(v)

def is_valid_variant(v: object) -> TypeGuard[str | Enum]:
    return isinstance(v, (str, Enum))

try:
    config = AnyModelConfig(**cfg)
except ValueError as e:
    if "'variant' field must be a string or Enum" in str(e):
        cfg['variant'] = cfg['variant'].value if isinstance(cfg['variant'], Enum) else str(cfg['variant'])
        config = AnyModelConfig(**cfg)
    else:
        raise

When it happens

Trigger: Creating a CLIP Embed config dict where 'variant' is present but is an int, bytes, or other object - e.g. {'type': 'clip_embed', 'format': 'diffusers', 'base': 'any', 'variant': 1}.

Common situations: Serialized CLIP Vision configs from older InvokeAI versions where variant was stored numerically; scripts generating configs with unconverted enum codes.

Related errors

• CLIP Embed model config dict must include a 'variant' field
• 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/51f0f6c67d91f35d. Report an issue: GitHub.