What causes "bad number of images passed: {len(imgs)}; expecting {self.batch_size} or less" in AUTOMATIC1111/stable-diffusion-webui?

Set batch_size >= len(images) (or chunk images into groups of at most batch_size and call once per chunk).

AUTOMATIC1111/stable-diffusion-webui · error · RuntimeError

bad number of images passed: {len(imgs)}; expecting {self.ba

Error message

bad number of images passed: {len(imgs)}; expecting {self.batch_size} or less

What it means

In img2img latent init: images are broadcast to the batch — 1 image is repeated to batch_size, and if len(imgs) <= batch_size the batch_size is shrunk to the image count. Only when MORE images than batch_size are supplied does this RuntimeError fire, since there is no defined way to map extra images onto the batch.

Source

Thrown at modules/processing.py:1722

            image = np.array(image).astype(np.float32) / 255.0
            image = np.moveaxis(image, 2, 0)

            imgs.append(image)

        if len(imgs) == 1:
            batch_images = np.expand_dims(imgs[0], axis=0).repeat(self.batch_size, axis=0)
            if self.overlay_images is not None:
                self.overlay_images = self.overlay_images * self.batch_size

            if self.color_corrections is not None and len(self.color_corrections) == 1:
                self.color_corrections = self.color_corrections * self.batch_size

        elif len(imgs) <= self.batch_size:
            self.batch_size = len(imgs)
            batch_images = np.array(imgs)
        else:
            raise RuntimeError(f"bad number of images passed: {len(imgs)}; expecting {self.batch_size} or less")

        image = torch.from_numpy(batch_images)
        image = image.to(shared.device, dtype=devices.dtype_vae)

        if opts.sd_vae_encode_method != 'Full':
            self.extra_generation_params['VAE Encoder'] = opts.sd_vae_encode_method

        self.init_latent = images_tensor_to_samples(image, approximation_indexes.get(opts.sd_vae_encode_method), self.sd_model)
        devices.torch_gc()

        if self.resize_mode == 3:
            self.init_latent = torch.nn.functional.interpolate(self.init_latent, size=(self.height // opt_f, self.width // opt_f), mode="bilinear")

        if image_mask is not None:
            init_mask = latent_mask
            latmask = init_mask.convert('RGB').resize((self.init_latent.shape[3], self.init_latent.shape[2]))
            latmask = np.moveaxis(np.array(latmask, dtype=np.float32), 2, 0) / 255
            latmask = latmask[0]

View on GitHub (pinned to 82a973c043)

Solutions

Set batch_size >= len(images) (or chunk images into groups of at most batch_size and call once per chunk).
Or pass a single image and let the code replicate it across the batch.
For API users: keep the number of elements in 'images' consistent with batch_size * n_iter handling — batch mode uses batch_size.

Example fix

# before
proc = process_images(img2img_proc(images=[a, b, c], batch_size=1))  # RuntimeError

# after
proc = process_images(img2img_proc(images=[a, b, c], batch_size=3))

Defensive patterns

Strategy: validation

Validate before calling

def prepare_img2img(proc, images):
    if len(images) > proc.batch_size:
        proc.batch_size = len(images)   # or chunk: images[i:i+proc.batch_size]
    return proc

proc = prepare_img2img(proc, imgs)

Try / catch

try:
    processed = process_images(p)
except RuntimeError as e:
    if 'bad number of images passed' in str(e):
        p.batch_size = len(imgs)
        processed = process_images(p)
    else:
        raise

Prevention

Chunk image lists into groups of size batch_size before calling img2img.
Keep API payload 'batch_size' >= number of images in the 'images' array.

When it happens

Trigger: Calling img2img/init_latent path with a list of images longer than processing.batch_size (e.g. batch_size=1 but 3 images passed, or an API payload whose image array exceeds its batch_size field).

Common situations: Batch img2img scripts that pass the whole folder at once while leaving batch_size at default 1; API clients that set n_iter for txt2img semantics but forget to raise batch_size for image arrays.

Related errors

AI-assisted analysis of AUTOMATIC1111/stable-diffusion-webui@82a973c043 (2026-08-14). Data as JSON: /api/errors/1d342619a6143b48. Report an issue: GitHub.