invoke-ai/InvokeAI · error · ExternalProviderCapabilityError

Reference images are not supported by {request.model.name}

Error message

Reference images are not supported by {request.model.name}

What it means

ExternalProviderCapabilityError raised by _validate_request when reference images are supplied but capabilities.supports_reference_images is False. The external model cannot accept reference image input at all.

Source

Thrown at invokeai/app/services/external_generation/external_generation_default.py:109

    def get_provider_statuses(self) -> dict[str, ExternalProviderStatus]:
        return {provider_id: provider.get_status() for provider_id, provider in self._providers.items()}

    def _validate_request(self, request: ExternalGenerationRequest) -> None:
        capabilities = request.model.capabilities

        self._logger.debug(
            "Validating external request provider=%s model=%s mode=%s supported=%s",
            request.model.provider_id,
            request.model.provider_model_id,
            request.mode,
            capabilities.modes,
        )

        if request.mode not in capabilities.modes:
            raise ExternalProviderCapabilityError(f"Mode '{request.mode}' is not supported by {request.model.name}")

        if request.reference_images and not capabilities.supports_reference_images:
            raise ExternalProviderCapabilityError(f"Reference images are not supported by {request.model.name}")

        if capabilities.max_reference_images is not None:
            if len(request.reference_images) > capabilities.max_reference_images:
                raise ExternalProviderCapabilityError(
                    f"{request.model.name} supports at most {capabilities.max_reference_images} reference images"
                )

        if capabilities.max_images_per_request is not None and request.num_images > capabilities.max_images_per_request:
            raise ExternalProviderCapabilityError(
                f"{request.model.name} supports at most {capabilities.max_images_per_request} images per request"
            )

        if capabilities.max_image_size is not None:
            if request.width > capabilities.max_image_size.width or request.height > capabilities.max_image_size.height:
                raise ExternalProviderCapabilityError(
                    f"{request.model.name} supports a maximum size of {capabilities.max_image_size.width}x{capabilities.max_image_size.height}"
                )

View on GitHub (pinned to 0b6a024f2f)

Solutions

Remove reference images from the request for this model
Select a model whose capabilities.supports_reference_images is True
Gate the reference-image UI/logic on the model's supports_reference_images capability

Example fix

// before
request.reference_images = [img]
service.generate(request)  # model doesn't support them

// after
if model.capabilities.supports_reference_images:
    request.reference_images = [img]
else:
    request.reference_images = []

Defensive patterns

Strategy: validation

Validate before calling

if request.reference_images and not request.model.capabilities.supports_reference_images:
    request.reference_images = []

Type guard

def accepts_reference_images(model) -> bool:
    return bool(getattr(model.capabilities, "supports_reference_images", False))

Try / catch

try:
    result = service.generate(request)
except ExternalProviderCapabilityError as e:
    if "Reference images" in str(e):
        request.reference_images = []
        result = service.generate(request)
    else:
        raise

Prevention

Hide/disable the reference-image input when the model doesn't support it
Clear reference images when switching to a non-supporting model
Encode per-model input requirements in capability metadata
Document which models accept reference images

When it happens

Trigger: generate() called with a non-empty request.reference_images list against a model whose capabilities report supports_reference_images=False.

Common situations: Passing reference images to a plain text-to-image model; UI that shows the reference-image uploader regardless of selected model; workflows reused across models with different capabilities.

Related errors

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