InpaintProcessor.preprocess returns a bare tensor when no mask is passed, breaking its own 3-value contract

[abhati27]

Describe the bug

InpaintProcessor.preprocess returns (image, mask, postprocessing_kwargs) on every path except the mask is None early return (image_processor.py#L895-L897), which returns the processed image on its own. Unpacking the three values the rest of the method promises then raises:

ValueError: not enough values to unpack (expected 3, got 1)

The return annotation is tuple[torch.Tensor, torch.Tensor], which no path actually returns, every masked path returns three values.

Both the early return and the three-value contract were introduced in the same commit (f50b18eec, #12220), so this looks like the early return simply not being updated when postprocessing_kwargs was added, rather than an intentional two-shape API.

Both in-repo call sites unpack three values (modular_pipelines/qwenimage/encoders.py#L1144 and #L1236), but their mask_image input is required=True, so they never reach the branch. It is reachable through direct use of InpaintProcessor, which is exported from diffusers and documented in docs/source/en/api/image_processor.md.

Reproduction

import numpy as np
import PIL.Image

from diffusers.image_processor import InpaintProcessor

image = PIL.Image.fromarray(np.zeros((64, 64, 3), dtype=np.uint8))
mask = PIL.Image.fromarray(np.zeros((64, 64), dtype=np.uint8))

processor = InpaintProcessor()

print(len(processor.preprocess(image, mask=mask, height=64, width=64)))  # 3
print(type(processor.preprocess(image, height=64, width=64)))            # <class 'torch.Tensor'>

img, msk, kwargs = processor.preprocess(image, height=64, width=64)

Output:

3
<class 'torch.Tensor'>
Traceback (most recent call last):
  ...
ValueError: not enough values to unpack (expected 3, got 1)

Logs

System Info

• 🤗 Diffusers version: 0.40.0.dev0 (main)
• Platform: macOS-26.6-arm64-arm-64bit-Mach-O
• Python version: 3.13.7
• PyTorch version (GPU?): 2.13.0 (False)
• Huggingface_hub version: 1.27.0
• Safetensors version: 0.8.0
• Accelerator: Apple M3
• Using GPU in script?: No
• Using distributed or parallel set-up in script?: No

Who can help?

@DN6 @yiyixuxu

[xquantize]

I dug into this and can confirm the inconsistency. The mask is None early return yields a single tensor while every masked path returns (image, mask, postprocessing_kwargs) and both in-repo call sites (qwenimage/encoders.py) unpack three, the -> tuple[torch.Tensor, torch.Tensor] annotation matches neither. It traces to #12220 (f50b18eec), where the early return wasn't updated when postprocessing_kwargs was added.

I have a fix plus a regression test ready: align the mask=None path to the same 3-tuple, mask=None, postprocessing_kwargs with None values (mirroring the existing no-crop branch) and correct the annotation to tuple[torch.Tensor, torch.Tensor | None, dict]. Since this changes the public return shape on the mask=None path I wanted to confirm you're happy with that direction before opening a PR, happy to instead keep two shapes and only fix the annotation if you'd prefer.

[lindicaphxag-tech]

PR #14807 follows the return-contract fix proposed here: the no-mask path returns the same three-value shape (image, None, postprocessing kwargs) as the masked path, and the annotation/regression test are updated. The repository checks for the PR are green. Could a maintainer assign/review it?