What causes "model does not match FLUX Tools Redux heuristics" in invoke-ai/InvokeAI?

Confirm the file is specifically a FLUX Tools Redux checkpoint (check keys against the heuristic expectations)

invoke-ai/InvokeAI · error · NotAMatchError

model does not match FLUX Tools Redux heuristics

Error message

model does not match FLUX Tools Redux heuristics

What it means

The FLUX Tools Redux config prober validates the candidate's state dict against is_state_dict_likely_flux_redux heuristics. Files that don't match the expected Redux key/shape pattern raise NotAMatchError, letting the model manager try other config types. This is a deliberate 'not this type' signal, not a crash.

Source

Thrown at invokeai/backend/model_manager/configs/flux_redux.py:38

    ModelType,
)


class FLUXRedux_Checkpoint_Config(Config_Base):
    """Model config for FLUX Tools Redux model."""

    type: Literal[ModelType.FluxRedux] = Field(default=ModelType.FluxRedux)
    format: Literal[ModelFormat.Checkpoint] = Field(default=ModelFormat.Checkpoint)
    base: Literal[BaseModelType.Flux] = Field(default=BaseModelType.Flux)

    @classmethod
    def from_model_on_disk(cls, mod: ModelOnDisk, override_fields: dict[str, Any]) -> Self:
        raise_if_not_file(mod)

        raise_for_override_fields(cls, override_fields)

        if not is_state_dict_likely_flux_redux(mod.load_state_dict()):
            raise NotAMatchError("model does not match FLUX Tools Redux heuristics")

        return cls(**override_fields)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Confirm the file is specifically a FLUX Tools Redux checkpoint (check keys against the heuristic expectations)
Let the probe continue — other config classes will match non-Redux adapters automatically
If it IS a Tools Redux file failing heuristics, update InvokeAI; key patterns change between releases
Use override_fields / explicit config assignment only if you are certain of the model type

Example fix

// before
# black-forest-labs/FLUX.1-Redux-dev imported expecting Tools Redux match
install_model("./flux1-redux-dev.safetensors")  # NotAMatchError
// after
# obtain the FLUX Tools Redux weights and import that file instead
install_model("./flux-tools-redux.safetensors")

Defensive patterns

Strategy: try-catch

Validate before calling

from safetensors import safe_open

def looks_like_redux(path) -> bool:
    with safe_open(path, framework="pt") as f:
        keys = f.keys()
    return any("redux" in k.lower() or k.startswith("proj") for k in keys)

Try / catch

try:
    config = probe(mod)
except NotAMatchError as e:
    if "FLUX Tools Redux" in str(e):
        config = probe(mod, candidate_classes=None)  # let other configs match
    else:
        raise

Prevention

Use official FLUX Tools Redux weights, not community renames
Let auto-probe pick the config class instead of forcing Redux
Keep InvokeAI updated as Redux key heuristics evolve
Verify adapter identity via key names before import

When it happens

Trigger: from_model_on_disk probing a safetensors file whose keys don't satisfy FLUX Redux heuristics — e.g. a regular FLUX Redux variant the heuristic doesn't recognize, a different adapter (IP-Adapter, ControlNet), or a renamed/re-keyed checkpoint.

Common situations: Importing a FLUX.1-Redux vs FLUX Tools Redux variant mismatch; downloading a redux-like adapter from a community repo with divergent keys; probing arbitrary adapters expecting the Redux config to match.

Related errors

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