invoke-ai/InvokeAI · error · ValueError

File extension {path.suffix} is not a recognized model forma

Error message

File extension {path.suffix} is not a recognized model format. Expected one of: {extensions}

What it means

_validate_path_looks_like_model pre-checks the path before probing. For a single file, the extension must be in _MODEL_EXTENSIONS (known weights formats). An unrecognized suffix (e.g. .json alone, .txt, .pth2, no extension) raises this ValueError so generic application directories aren't misinterpreted as models.

Source

Thrown at invokeai/backend/model_manager/configs/factory.py:564

    @staticmethod
    def _validate_path_looks_like_model(path: Path) -> None:
        """Perform basic sanity checks to ensure a path looks like a model.

        This prevents wasting time trying to identify obviously non-model paths like
        home directories or downloads folders. Raises RuntimeError if the path doesn't
        pass basic checks.

        Args:
            path: The path to validate

        Raises:
            ValueError: If the path doesn't look like a model
        """
        if path.is_file():
            # For files, just check the extension
            if path.suffix.lower() not in _MODEL_EXTENSIONS:
                raise ValueError(
                    f"File extension {path.suffix} is not a recognized model format. "
                    f"Expected one of: {', '.join(sorted(_MODEL_EXTENSIONS))}"
                )
        else:
            # Recognized Diffusers/Transformers configs are safe model markers. A generic config.json
            # is not sufficient because many large application directories contain one.
            recognized_root_config = False
            for config_name in _CONFIG_FILES:
                config_path = path / config_name
                if not config_path.exists():
                    continue
                try:
                    # Model config.json files are UTF-8; read explicitly so a non-ASCII value does not
                    # raise UnicodeDecodeError under a cp1252 (Windows) locale and get mis-treated as
                    # "unrecognized", which would wrongly reject a valid model directory.
                    config = json.loads(config_path.read_text(encoding="utf-8"))
                except (OSError, ValueError):
                    continue

View on GitHub (pinned to 0b6a024f2f)

Solutions

Point at the actual weights file (.safetensors, .ckpt, .bin, etc.) instead of the config/README
Rename the file with a recognized model extension if it truly is weights saved with a wrong suffix
Check for incomplete downloads (e.g. .part/.tmp) and re-download fully
For diffusers-style models, pass the parent directory containing the config plus weights, not the config file alone

Example fix

// before
install_model("/models/my-model/config.json")
// after
install_model("/models/my-model/diffusion_pytorch_model.safetensors")
# or the directory:
install_model("/models/my-model")

Defensive patterns

Strategy: validation

Validate before calling

import pathlib

_MODEL_EXTENSIONS = {".safetensors", ".ckpt", ".pt", ".bin", ".pth", ".gguf"}

def validate_model_file(path: str) -> pathlib.Path:
    p = pathlib.Path(path)
    if p.is_file() and p.suffix.lower() not in _MODEL_EXTENSIONS:
        raise ValueError(f"{p.suffix} is not a model extension; pass a weights file or model directory")
    return p

Type guard

def is_model_file(path: str) -> bool:
    from invokeai.backend.model_manager.configs.factory import _MODEL_EXTENSIONS
    p = pathlib.Path(path)
    return p.is_file() and p.suffix.lower() in _MODEL_EXTENSIONS

Try / catch

try:
    install_model(path)
except ValueError as e:
    if "not a recognized model format" in str(e):
        logger.error("Point at a weights file (.safetensors/.ckpt/...) or its directory")
    else:
        raise

Prevention

Never pass config.json, README or download stubs to the installer
Finish downloads before importing (no .part/.tmp files)
Use directory imports for diffusers-style repos
Check file extensions in your import UI before calling the API

When it happens

Trigger: Calling model install/probe APIs (from_model_on_disk path) with a file whose suffix is not a recognized model extension — e.g. pointing at a README, a config .json file, a .partial download, or an extensionless binary.

Common situations: Passing a transformers config.json directly instead of the weights file; incomplete downloads left with temp extensions; choosing the wrong file inside a model repo folder; typo'd extension after manual rename.

Related errors

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