invoke-ai/InvokeAI · error · ExternalProviderCapabilityError

Mode '{request.mode}' requires an init image for {request.mo

Error message

Mode '{request.mode}' requires an init image for {request.model.name}

What it means

InvokeAI's external generation service validates that generation requests using image-conditioned modes actually carry the input image. If the requested mode (e.g. 'img2img' or 'inpaint', or any mode listed in the model's capabilities.input_image_required_for) is selected but request.init_image is None, an ExternalProviderCapabilityError is raised before calling the provider. This is a client-side pre-flight validation to avoid wasted provider API calls.

Source

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

                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
        updates: dict[str, object] = {}

        if request.seed is not None and not capabilities.supports_seed:
            self._logger.debug(
                "Dropping seed for %s: model does not support seed control",
                request.model.name,

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Attach an init image to the request (set request.init_image before calling generate)
  2. Change request.mode to a text-only mode such as 'txt2img' if an init image is not needed
  3. Check the selected model's capabilities.input_image_required_for to know which modes need an init image
  4. In workflows, connect an image source (upload, load-image node) to the img2img/inpaint node's image input

Example fix

// before
request = ExternalGenerationRequest(model=model, mode='img2img', prompt='a cat')
result = service.generate(request)  # raises
// after
request = ExternalGenerationRequest(model=model, mode='img2img', prompt='a cat', init_image=my_image)
result = service.generate(request)
Defensive patterns

Strategy: validation

Validate before calling

required_modes = getattr(model.capabilities, 'input_image_required_for', None) or ['img2img', 'inpaint']
if request.mode in required_modes and request.init_image is None:
    raise ValueError(f"{request.mode!r} on {model.name} requires an init image")
# only then call generate(request)

Type guard

def has_init_image(req) -> bool:
    return getattr(req, 'init_image', None) is not None

Try / catch

from invokeai.app.services.external_generation import ExternalProviderCapabilityError
try:
    result = service.generate(request)
except ExternalProviderCapabilityError as e:
    log.warning("capability validation failed: %s", e)
    request = replace(request, mode='txt2img')  # or attach an init image
    result = service.generate(request)

Prevention

When it happens

Trigger: Calling generate() with request.mode in required_modes (default ['img2img','inpaint'] or the model's input_image_required_for list) while request.init_image is None. Typical when a workflow-editor node wires a mode without connecting an init image input.

Common situations: Users build a workflow with an img2img/inpaint node but leave the image input unconnected; API clients construct ExternalGenerationRequest programmatically and omit init_image; a model recently added input_image_required_for to its capabilities and old requests no longer satisfy it.

Related errors

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