invoke-ai/InvokeAI · error · NotAMatchError

unknown override field: {field_name}

Error message

unknown override field: {field_name}

What it means

raise_for_override_fields validates user-supplied override fields against the candidate config class's pydantic model_fields before applying them in from_model_on_disk. If an override key does not exist on that config class, NotAMatchError is raised. This prevents silently ignoring typos or fields that belong to a different config class.

Source

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

def raise_for_override_fields(candidate_config_class: type[BaseModel], override_fields: dict[str, Any]) -> None:
    """Check if the provided override fields are valid for the config class using pydantic.

    For example, if the candidate config class has a field "base" of type Literal[BaseModelType.StableDiffusion1], and
    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")

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Check the candidate config class's pydantic fields and correct the override field name spelling.
2. Remove overrides that don't apply to this model type.
3. Use the config record's `default_settings` or the correct config class that defines the field.
4. Update client code if the field was renamed in a newer InvokeAI version.

Example fix

// before
from_model_on_disk(mod, config_class, override_fields={"varient": "fp16"})
// after
from_model_on_disk(mod, config_class, override_fields={"variant": "fp16"})

valid = set(candidate_config_class.model_fields)
bad = set(override_fields) - valid
assert not bad, f"unknown override fields: {bad}; valid fields: {sorted(valid)}"

def overrides_are_known(cfg_cls, overrides: dict) -> bool:
    return all(k in cfg_cls.model_fields for k in overrides)

try:
    record = from_model_on_disk(mod, config_class, override_fields=overrides)
except NotAMatchError as e:
    if "unknown override field" in str(e):
        logger.error("bad override fields in request: %s", e)
        raise HTTPException(422, str(e)) from e

When it happens

Trigger: Calling from_model_on_disk with override_fields containing a key not defined on the candidate config class (e.g. override field "variant" on a config that has no such pydantic field).

Common situations: Typos in override field names; copying overrides between different model types (checkpoint vs diffusers vs LoRA configs); API invocations from stale clients using fields removed in an InvokeAI version bump.

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/70fc938eb967842d. Report an issue: GitHub.