{"record":{"id":"64f6054a43c9d206","repo":"invoke-ai/InvokeAI","slug":"mode-request-mode-requires-an-init-image-for","errorCode":null,"errorMessage":"Mode '{request.mode}' requires an init image for {request.model.name}","messagePattern":"Mode '(.+?)' requires an init image for (.+?)","errorType":"exception","errorClass":"ExternalProviderCapabilityError","httpStatus":null,"severity":"error","filePath":"invokeai/app/services/external_generation/external_generation_default.py","lineNumber":142,"sourceCode":"                raise ExternalProviderCapabilityError(\n                    f\"{request.model.name} supports a maximum size of {capabilities.max_image_size.width}x{capabilities.max_image_size.height}\"\n                )\n\n        if capabilities.allowed_aspect_ratios:\n            aspect_ratio = _format_aspect_ratio(request.width, request.height)\n            if aspect_ratio not in capabilities.allowed_aspect_ratios:\n                size_ratio = None\n                if capabilities.aspect_ratio_sizes:\n                    size_ratio = _ratio_for_size(request.width, request.height, capabilities.aspect_ratio_sizes)\n                if size_ratio is None or size_ratio not in capabilities.allowed_aspect_ratios:\n                    ratio_label = size_ratio or aspect_ratio\n                    raise ExternalProviderCapabilityError(\n                        f\"{request.model.name} does not support aspect ratio {ratio_label}\"\n                    )\n\n        required_modes = capabilities.input_image_required_for or [\"img2img\", \"inpaint\"]\n        if request.mode in required_modes and request.init_image is None:\n            raise ExternalProviderCapabilityError(\n                f\"Mode '{request.mode}' requires an init image for {request.model.name}\"\n            )\n\n        if request.mode == \"inpaint\" and request.mask_image is None:\n            raise ExternalProviderCapabilityError(\n                f\"Mode '{request.mode}' requires a mask image for {request.model.name}\"\n            )\n\n    def _drop_unsupported_capabilities(self, request: ExternalGenerationRequest) -> ExternalGenerationRequest:\n        \"\"\"Silently drop request fields the selected model does not support so workflow-editor runs don't fail\n        when users wire them in regardless.\"\"\"\n        capabilities = request.model.capabilities\n        updates: dict[str, object] = {}\n\n        if request.seed is not None and not capabilities.supports_seed:\n            self._logger.debug(\n                \"Dropping seed for %s: model does not support seed control\",\n                request.model.name,","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/services/external_generation/external_generation_default.py#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Attach an init image to the request (set request.init_image before calling generate)","Change request.mode to a text-only mode such as 'txt2img' if an init image is not needed","Check the selected model's capabilities.input_image_required_for to know which modes need an init image","In workflows, connect an image source (upload, load-image node) to the img2img/inpaint node's image input"],"exampleFix":"// before\nrequest = ExternalGenerationRequest(model=model, mode='img2img', prompt='a cat')\nresult = service.generate(request)  # raises\n// after\nrequest = ExternalGenerationRequest(model=model, mode='img2img', prompt='a cat', init_image=my_image)\nresult = service.generate(request)","handlingStrategy":"validation","validationCode":"required_modes = getattr(model.capabilities, 'input_image_required_for', None) or ['img2img', 'inpaint']\nif request.mode in required_modes and request.init_image is None:\n    raise ValueError(f\"{request.mode!r} on {model.name} requires an init image\")\n# only then call generate(request)","typeGuard":"def has_init_image(req) -> bool:\n    return getattr(req, 'init_image', None) is not None","tryCatchPattern":"from invokeai.app.services.external_generation import ExternalProviderCapabilityError\ntry:\n    result = service.generate(request)\nexcept ExternalProviderCapabilityError as e:\n    log.warning(\"capability validation failed: %s\", e)\n    request = replace(request, mode='txt2img')  # or attach an init image\n    result = service.generate(request)","preventionTips":["Check model.capabilities.input_image_required_for when building requests","In workflows, validate node inputs (image connected) before invoking generation","Default to 'txt2img' when no init image is available"],"tags":["validation","request-validation","image-input","external-provider"],"backgroundTag":"missing-required-input","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}