invoke-ai/InvokeAI · error · ValueError

External API models cannot be loaded from disk

Error message

External API models cannot be loaded from disk

What it means

Static guard _raise_if_external rejects loading models that are not local: models whose base is BaseModelType.External or whose format is ModelFormat.ExternalApi (third-party hosted API models). Such models have no files on disk or local weights to load, so loading them from disk is meaningless and blocked with a ValueError.

Source

Thrown at invokeai/app/services/shared/invocation_context.py:606

        """Move a model (and all of its submodels) from VRAM to RAM, freeing its VRAM but keeping it cached.

        Use this when an invocation is done with a model for the rest of the run - e.g. a one-shot text encoder -
        so the next, larger load does not have to compete with it for VRAM. The model stays in the RAM cache, so
        a subsequent load only re-streams it back to VRAM rather than rebuilding it from disk.

        Args:
            identifier: The key or ModelField representing the model to offload.

        Returns:
            The number of VRAM bytes freed.
        """
        key = identifier if isinstance(identifier, str) else identifier.key
        return self._services.model_manager.load.ram_cache.offload_model_from_vram(key)

    @staticmethod
    def _raise_if_external(model: AnyModelConfig) -> None:
        if model.base == BaseModelType.External or model.format == ModelFormat.ExternalApi:
            raise ValueError("External API models cannot be loaded from disk")

    def get_config(self, identifier: Union[str, "ModelIdentifierField"]) -> AnyModelConfig:
        """Get a model's config.

        Args:
            identifier: The key or ModelField representing the model.

        Returns:
            The model's config.
        """
        if isinstance(identifier, str):
            return self._services.model_manager.store.get_model(identifier)
        else:
            return self._services.model_manager.store.get_model(identifier.key)

    def search_by_path(self, path: Path) -> list[AnyModelConfig]:
        """Search for models by path.

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Use the API-generation path for external models instead of local loading
  2. Reference a local model (non-external base/format) in the loader call
  3. Check model.base and model.format before calling load and skip external models

Example fix

// before
model = ctx.models.load(key=field.key)
// after
config = ctx.models.get_config(field.key)
if config.base == BaseModelType.External or config.format == ModelFormat.ExternalApi:
    raise RuntimeError(f"{config.name} is an external API model; use the remote API path")
model = ctx.models.load(key=field.key)
Defensive patterns

Strategy: validation

Validate before calling

config = ctx.models.get_config(key)
if config.base == BaseModelType.External or config.format == ModelFormat.ExternalApi:
    raise RuntimeError(f"{config.name} is an external API model and cannot be loaded locally")

Type guard

def is_external_model(cfg: AnyModelConfig) -> bool:
    return cfg.base == BaseModelType.External or cfg.format == ModelFormat.ExternalApi

Try / catch

try:
    model = ctx.models.load(key=key)
except ValueError as e:
    if "External API models" in str(e):
        logger.warning("Key %s is external; use the API generation path", key)
        model = None
    else:
        raise

Prevention

When it happens

Trigger: Calling ctx.models.load(key) or load_by_attrs(...) on a model config representing an External/ExternalApi model (e.g. a remote API-hosted model entry).

Common situations: Configuring a workflow that references an external API model and then attempting a local load path; switching a model record to external format and re-running an old loader call; tests verifying external models cannot be loaded.

Related errors

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