invoke-ai/InvokeAI · error · ExternalProviderCapabilityError

{request.model.name} supports at most {capabilities.max_refe

Error message

{request.model.name} supports at most {capabilities.max_reference_images} reference images

What it means

ExternalProviderCapabilityError raised by _validate_request when the number of reference images in the request exceeds capabilities.max_reference_images. The model supports reference images, but only up to a fixed maximum.

Source

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

        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}"
                )

        if capabilities.allowed_aspect_ratios:
            aspect_ratio = _format_aspect_ratio(request.width, request.height)
            if aspect_ratio not in capabilities.allowed_aspect_ratios:
                size_ratio = None

View on GitHub (pinned to 0b6a024f2f)

Solutions

Trim the reference_images list to at most capabilities.max_reference_images
Choose a model with a higher max_reference_images limit
Split the workload into multiple requests, each within the limit

Example fix

// before
request.reference_images = imgs  # 5 images, limit is 2

// after
request.reference_images = imgs[: model.capabilities.max_reference_images]

Defensive patterns

Strategy: validation

Validate before calling

max_refs = request.model.capabilities.max_reference_images
if max_refs is not None:
    request.reference_images = request.reference_images[:max_refs]

Type guard

def within_reference_limit(model, images: list) -> bool:
    mx = model.capabilities.max_reference_images
    return mx is None or len(images) <= mx

Try / catch

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

Prevention

Enforce max_reference_images in the upload UI (disable the add button at the cap)
Truncate or paginate reference image batches before submission
Surface the model's limit in tooltips/help text
Split large multi-reference jobs across requests

When it happens

Trigger: len(request.reference_images) > capabilities.max_reference_images (when max_reference_images is not None) during generate()'s validation pass.

Common situations: Uploading more reference images than the provider allows (e.g. several refs against a single-ref model); batch UIs accumulating images without checking the cap.

Related errors

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