invoke-ai/InvokeAI · error · ExternalProviderCapabilityError

{request.model.name} does not support aspect ratio {ratio_la

Error message

{request.model.name} does not support aspect ratio {ratio_label}

What it means

ExternalProviderCapabilityError raised by _validate_request when the request's aspect ratio (exact or size-derived, via _format_aspect_ratio / _ratio_for_size) is not in capabilities.allowed_aspect_ratios. The model only generates images at a fixed set of aspect ratios.

Source

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

            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(
                        f"{request.model.name} does not support aspect ratio {ratio_label}"
                    )

        required_modes = capabilities.input_image_required_for or ["img2img", "inpaint"]
        if request.mode in required_modes and request.init_image is None:
            raise ExternalProviderCapabilityError(
                f"Mode '{request.mode}' requires an init image for {request.model.name}"
            )

        if request.mode == "inpaint" and request.mask_image is None:
            raise ExternalProviderCapabilityError(
                f"Mode '{request.mode}' requires a mask image for {request.model.name}"
            )

    def _drop_unsupported_capabilities(self, request: ExternalGenerationRequest) -> ExternalGenerationRequest:
        """Silently drop request fields the selected model does not support so workflow-editor runs don't fail
        when users wire them in regardless."""
        capabilities = request.model.capabilities

View on GitHub (pinned to 0b6a024f2f)

Solutions

Round width/height to the nearest allowed aspect ratio from capabilities.allowed_aspect_ratios (use capabilities.aspect_ratio_sizes for concrete dimensions)
Generate at the closest allowed ratio and crop/extend locally
Select a model without the allowed_aspect_ratios restriction
Constrain the size picker UI to the model's allowed ratios

Example fix

// before
request.width, request.height = 1200, 700  # unsupported ratio

// after
ratios = model.capabilities.allowed_aspect_ratios
nearest = min(ratios, key=lambda r: abs(eval_ratio(r) - request.width / request.height))
request.width, request.height = dims_for_ratio(nearest, base=1024)

Defensive patterns

Strategy: validation

Validate before calling

ratios = request.model.capabilities.allowed_aspect_ratios
if ratios:
    target = request.width / request.height
    best = min(ratios, key=lambda r: abs(eval_ratio(r) - target))
    request.width, request.height = dims_for_ratio(best, base=request.model.capabilities.aspect_ratio_sizes or {})

Type guard

def aspect_ratio_allowed(model, width: int, height: int) -> bool:
    allowed = model.capabilities.allowed_aspect_ratios
    if not allowed:
        return True
    from invokeai.app.services.external_generation.external_generation_default import _format_aspect_ratio
    return _format_aspect_ratio(width, height) in allowed

Try / catch

try:
    result = service.generate(request)
except ExternalProviderCapabilityError as e:
    if "aspect ratio" in str(e):
        snap_request_to_nearest_allowed_ratio(request)
        result = service.generate(request)
    else:
        raise

Prevention

Restrict the size/aspect picker to capabilities.allowed_aspect_ratios
Snap arbitrary canvas sizes to the nearest allowed ratio before submit
Use capabilities.aspect_ratio_sizes to offer concrete allowed dimensions
Crop or outpaint locally when an exact custom ratio is required

When it happens

Trigger: generate() called with width/height whose formatted aspect ratio is not allowed, and even the size-derived ratio from capabilities.aspect_ratio_sizes is None or not allowed.

Common situations: Custom canvas sizes in the UI (e.g. 1200x700) sent to a model that only accepts 1:1, 3:2, 2:3, etc.; portrait/landscape presets from one model used with a more restrictive model.

Related errors

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