invoke-ai/InvokeAI · error · NotAMatchError

invalid override for field '{field_name}': {e}

Error message

invalid override for field '{field_name}': {e}

What it means

After confirming the override field exists, raise_for_override_fields runs PydanticFieldValidator.validate_field to check the value's type/allowed values against the config class. A pydantic ValidationError is wrapped (chained) as NotAMatchError with the field name and original validation message. This keeps override failures within InvokeAI's uniform NotAMatch probing flow.

Source

Thrown at invokeai/backend/model_manager/configs/identification_utils.py:154

    the override fields contain "base": BaseModelType.Flux, this function will raise NotAMatch.

    Internally, this function extracts the pydantic schema for each individual override field from the candidate config
    class and validates the override value against that schema. Post-instantiation validators are not run.

    Args:
        candidate_config_class: The config class that is being tested.
        override_fields: The override fields provided by the user.

    Raises:
        NotAMatch if any override field is invalid for the config class.
    """
    for field_name, override_value in override_fields.items():
        if field_name not in candidate_config_class.model_fields:
            raise NotAMatchError(f"unknown override field: {field_name}")
        try:
            PydanticFieldValidator.validate_field(candidate_config_class, field_name, override_value)
        except ValidationError as e:
            raise NotAMatchError(f"invalid override for field '{field_name}': {e}") from e


def raise_if_not_file(mod: ModelOnDisk) -> None:
    """Raise NotAMatch if the model path is not a file."""
    if not mod.path.is_file():
        raise NotAMatchError("model path is not a file")


def raise_if_not_dir(mod: ModelOnDisk) -> None:
    """Raise NotAMatch if the model path is not a directory."""
    if not mod.path.is_dir():
        raise NotAMatchError("model path is not a directory")


def state_dict_has_any_keys_exact(state_dict: dict[str | int, Any], keys: str | set[str]) -> bool:
    """Returns true if the state dict has any of the specified keys."""
    _keys = {keys} if isinstance(keys, str) else keys
    return any(key in state_dict for key in _keys)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Read the chained pydantic message to see which field value failed and why.
2. Use the exact enum/Literal values the config class defines (e.g. BaseModelType.StableDiffusion1, ModelType.IpAdapter, ModelFormat.Diffusers).
3. Pre-validate overrides with the config class's pydantic model (e.g. CandidateConfig.model_validate(overrides)) before calling.
4. Fix client/API payloads that send wrong types (strings vs ints).

Example fix

// before
override_fields = {"base": "sd-1"}
// after
from invokeai.backend.model_manager import BaseModelType
override_fields = {"base": BaseModelType.StableDiffusion1}

from pydantic import ValidationError
try:
    candidate_config_class.model_validate({**defaults, **override_fields})
except ValidationError as e:
    raise ValueError(f"invalid overrides: {e}") from e

def overrides_are_valid(cfg_cls, overrides: dict) -> bool:
    from pydantic import ValidationError
    try:
        cfg_cls.model_validate(dict(overrides))
        return True
    except ValidationError:
        return False

try:
    record = from_model_on_disk(mod, config_class, override_fields=overrides)
except NotAMatchError as e:
    if "invalid override" in str(e):
        logger.error("override value rejected: %s", e)
        raise HTTPException(422, str(e)) from e

When it happens

Trigger: Calling from_model_on_disk with override_fields whose value violates the field's pydantic type or Literal constraints (e.g. base="sd-1" instead of BaseModelType.StableDiffusion1, or an out-of-enum model_format).

Common situations: Passing raw strings where enums/Literals are expected; wrong variant/format names; numeric types where strings are required; overrides constructed from user input without pre-validation.

Related errors

• cfg_scale values must be finite.
• shift must be finite.
• Cannot divide by zero
• source_url must be a string
• source_url must be an http or https URL

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