invoke-ai/InvokeAI · error · NotAMatchError

missing ip_adapter.bin weights file

Error message

missing ip_adapter.bin weights file

What it means

IPAdapterModelConfig expects IP-Adapters in diffusers folder layout to include an `ip_adapter.bin` weights file at the folder root. _validate_has_weights_file checks for its existence and raises NotAMatchError if absent, distinguishing real IP-Adapter folders from other diffusers folders during probing.

Source

Thrown at invokeai/backend/model_manager/configs/ip_adapter.py:66

        cls._validate_has_image_encoder_metadata_file(mod)

        cls._validate_base(mod)

        return cls(**override_fields)

    @classmethod
    def _validate_base(cls, mod: ModelOnDisk) -> None:
        """Raise `NotAMatch` if the model base does not match this config class."""
        expected_base = cls.model_fields["base"].default
        recognized_base = cls._get_base_or_raise(mod)
        if expected_base is not recognized_base:
            raise NotAMatchError(f"base is {recognized_base}, not {expected_base}")

    @classmethod
    def _validate_has_weights_file(cls, mod: ModelOnDisk) -> None:
        weights_file = mod.path / "ip_adapter.bin"
        if not weights_file.exists():
            raise NotAMatchError("missing ip_adapter.bin weights file")

    @classmethod
    def _validate_has_image_encoder_metadata_file(cls, mod: ModelOnDisk) -> None:
        image_encoder_metadata_file = mod.path / "image_encoder.txt"
        if not image_encoder_metadata_file.exists():
            raise NotAMatchError("missing image_encoder.txt metadata file")

    @classmethod
    def _get_base_or_raise(cls, mod: ModelOnDisk) -> BaseModelType:
        state_dict = mod.load_state_dict()

        try:
            cross_attention_dim = state_dict["ip_adapter"]["1.to_k_ip.weight"].shape[-1]
        except Exception as e:
            raise NotAMatchError(f"unable to determine cross attention dimension: {e}") from e

        match cross_attention_dim:
            case 768:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Rename the weights file to ip_adapter.bin inside the model folder (if it is the same format).
2. Re-download the complete IP-Adapter repository including ip_adapter.bin.
3. If your release only ships .safetensors, update InvokeAI to a version supporting that layout or add the .bin file.
4. Verify with Path.exists() that the folder layout matches diffusers IP-Adapter conventions.

Example fix

// before
models/ip_adapter_sd15/{image_encoder/, model.safetensors}
// after
models/ip_adapter_sd15/{image_encoder/, ip_adapter.bin, image_encoder.txt}

from pathlib import Path
d = Path(model_dir)
assert d.is_dir() and (d / "ip_adapter.bin").exists(), f"not a valid IP-Adapter folder, missing ip_adapter.bin: {d}"

def is_ip_adapter_folder(p) -> bool:
    from pathlib import Path
    d = Path(p)
    return d.is_dir() and (d / "ip_adapter.bin").exists() and (d / "image_encoder").is_dir()

try:
    record = from_model_on_disk(mod)
except NotAMatchError as e:
    if "missing ip_adapter.bin" in str(e):
        logger.warning("folder lacks ip_adapter.bin; not registrable as IP-Adapter: %s", mod.path)

When it happens

Trigger: from_model_on_disk probing a directory without ip_adapter.bin using an IP-Adapter config class; weights renamed to .safetensors or moved into a subfolder.

Common situations: Newer h94/IP-Adapter releases ship ip_adapter.safetensors instead of .bin; partial downloads; users extracting only the image_encoder folder; custom repackaged adapters with different filenames.

Related errors

• missing image_encoder.txt metadata file
• Unsupported IP-Adapter base type: '{ip_adapter_info.base}'.
• Unexpected IP-Adapter method: '{self.method}'.
• base is {recognized_base}, not {expected_base}
• unable to determine cross attention dimension: {e}

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