invoke-ai/InvokeAI · error · NotAMatchError

missing image_encoder.txt metadata file

Error message

missing image_encoder.txt metadata file

What it means

IP-Adapter folders with a CLIP Vision image encoder require an `image_encoder.txt` metadata file that records the source (e.g. the OpenCLIP image encoder repo/hash) for the image_encoder subfolder. _validate_has_image_encoder_metadata_file raises NotAMatchError when that file is missing, because InvokeAI needs the metadata to identify the encoder.

Source

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

    @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:
                return BaseModelType.StableDiffusion1
            case 1024:
                return BaseModelType.StableDiffusion2
            case 2048:
                return BaseModelType.StableDiffusionXL
            case _:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Re-download the full IP-Adapter folder so image_encoder.txt is included.
2. Recreate image_encoder.txt with the expected metadata (image encoder source) if you know it.
3. Copy the file from the original h94/IP-Adapter release matching your adapter.
4. Verify the folder contents against the upstream repo before registering.

Example fix

// before
models/ip_adapter_sd15/{ip_adapter.bin, image_encoder/}
// after
echo "https://huggingface.co/h94/IP-Adapter/..." > models/ip_adapter_sd15/image_encoder.txt

from pathlib import Path
d = Path(model_dir)
assert (d / "image_encoder.txt").exists(), f"missing image_encoder.txt metadata sidecar in {d}"

def has_image_encoder_metadata(p) -> bool:
    from pathlib import Path
    d = Path(p)
    return d.is_dir() and (d / "image_encoder.txt").is_file() and (d / "image_encoder").is_dir()

try:
    record = from_model_on_disk(mod)
except NotAMatchError as e:
    if "missing image_encoder.txt" in str(e):
        logger.warning("IP-Adapter folder lacks encoder metadata file: %s", mod.path)

When it happens

Trigger: from_model_on_disk probing an IP-Adapter directory that contains ip_adapter.bin and image_encoder weights but lacks the image_encoder.txt sidecar file.

Common situations: Manually copying only weights from the h94/IP-Adapter repo and skipping the .txt metadata; third-party re-uploads that omit it; cleaning scripts deleting 'extra' text files.

Related errors

• missing ip_adapter.bin weights 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/2fd358942b7a033a. Report an issue: GitHub.