invoke-ai/InvokeAI · error · ExternalProviderCapabilityError

Mode '{request.mode}' requires a mask image for {request.mod

Error message

Mode '{request.mode}' requires a mask image for {request.model.name}

What it means

InvokeAI requires a mask image whenever the generation mode is 'inpaint'. The validation in _validate_request raises ExternalProviderCapabilityError if request.mask_image is None for inpaint mode, because inpainting is undefined without a mask telling the provider which pixels to regenerate. This fails fast before any network call.

Source

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

            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,
            )
            updates["seed"] = None

        if updates:
            return dataclasses.replace(request, **updates)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Provide request.mask_image (a mask aligned with the init image) before calling generate
Switch request.mode to 'img2img' or 'txt2img' if masking is not intended
In the UI/workflow editor, connect or draw a mask for the inpaint node
Verify the mask dimensions match the init image to avoid downstream provider errors

Example fix

// before
request = ExternalGenerationRequest(model=model, mode='inpaint', prompt='fix sky', init_image=img)
result = service.generate(request)  # raises
// after
request = ExternalGenerationRequest(model=model, mode='inpaint', prompt='fix sky', init_image=img, mask_image=mask)
result = service.generate(request)

Defensive patterns

Strategy: validation

Validate before calling

if request.mode == 'inpaint' and request.mask_image is None:
    raise ValueError("inpaint mode requires a mask image")
# then call generate(request)

Type guard

def has_mask(req) -> bool:
    return getattr(req, 'mask_image', None) is not None

Try / catch

try:
    result = service.generate(request)
except ExternalProviderCapabilityError as e:
    if 'mask image' in str(e):
        request = replace(request, mode='img2img')  # degrade gracefully or prompt user for a mask
    raise

Prevention

Always pair inpaint requests with a mask aligned to the init image
Validate mode/image/mask combinations client-side before generate()
In UIs, disable the inpaint action until a mask exists

When it happens

Trigger: Calling generate() with request.mode == 'inpaint' and request.mask_image is None. The init image check (620) passes but the mask check then fails.

Common situations: Workflow nodes wired for inpaint without a mask input; API scripts that set mode='inpaint' and an init image but forget the mask; UI paths that default to inpaint mode when a mask hasn't been drawn yet.

Related errors

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