invoke-ai/InvokeAI · error · ExternalProviderCapabilityError

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

Error message

{request.model.name} supports at most {capabilities.max_images_per_request} images per request

What it means

ExternalProviderCapabilityError raised by _validate_request when request.num_images exceeds capabilities.max_images_per_request. The provider caps how many images a single generation call may produce.

Source

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

            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
                if capabilities.aspect_ratio_sizes:
                    size_ratio = _ratio_for_size(request.width, request.height, capabilities.aspect_ratio_sizes)
                if size_ratio is None or size_ratio not in capabilities.allowed_aspect_ratios:
                    ratio_label = size_ratio or aspect_ratio
                    raise ExternalProviderCapabilityError(

View on GitHub (pinned to 0b6a024f2f)

Solutions

Lower request.num_images to capabilities.max_images_per_request
Issue multiple sequential requests to reach the desired total count
Clamp num_images in the UI from the model's capabilities before submitting

Example fix

// before
request.num_images = 10  # model allows 4

// after
request.num_images = min(10, model.capabilities.max_images_per_request or 10)

Defensive patterns

Strategy: validation

Validate before calling

mx = request.model.capabilities.max_images_per_request
if mx is not None:
    request.num_images = min(request.num_images, mx)

Type guard

def within_image_count_limit(model, num_images: int) -> bool:
    mx = model.capabilities.max_images_per_request
    return mx is None or num_images <= mx

Try / catch

try:
    result = service.generate(request)
except ExternalProviderCapabilityError as e:
    if "images per request" in str(e):
        request.num_images = request.model.capabilities.max_images_per_request
        result = service.generate(request)
    else:
        raise

Prevention

Cap the num_images UI control at the selected model's maximum
Don't persist num_images across model switches without clamping
Fan out into multiple requests when a larger total is needed
Read the limit from capabilities rather than hardcoding

When it happens

Trigger: generate() called with request.num_images > capabilities.max_images_per_request (when that cap is set).

Common situations: User sets 'number of images' higher than the model permits; saved UI settings carry a large num_images to a more restrictive model; batch scripts hardcoding a count.

Related errors

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