deepfakes/faceswap · error · FaceswapError

The output size of the selected model is too small for MS-SS

Error message

The output size of the selected model is too small for MS-SSIM. Use SSIM instead.

What it means

MSSIMLoss validates at first forward pass that the smallest down-scaled image is at least the Gaussian kernel size; for tiny model outputs it shrinks the kernel, but if the adjusted filter size would drop below 3px the loss cannot be computed and a FaceswapError advises switching to SSIM. The validation triggers on output images below roughly 176px and fails hard only for very small outputs.

Source

Thrown at lib/model/losses/perceptual_loss.py:455

        if self._validated:
            return
        im_size = image.shape[2]
        smallest_scale = self._get_smallest_size(im_size, len(self._power_factors) - 1)
        kernel_size = self._kernel.shape[-1]

        if smallest_scale >= kernel_size:
            logger.info("[MSSIM] Inbound images are valid. smallest_scale: %s, kernel_size: %s",
                        smallest_scale, kernel_size)
            self._validated = True
            return

        logger.warning("[MSSIM] Output size %spx is below 176px. The MS-SSIM kernel must be "
                       "adjusted to accommodate. You will likely get better results using SSIM.",
                       im_size)
        del self._kernel
        flt = smallest_scale - 1 if smallest_scale % 2 == 0 else smallest_scale
        if flt < 3:
            raise FaceswapError("The output size of the selected model is too small for MS-SSIM. "
                                "Use SSIM instead.")
        logger.debug("[MSSIM] Adjusting filter kernel to %s from %s for smallest scale %s.",
                     flt, kernel_size, smallest_scale)
        self._kernel = self._fspecial_gauss(flt, self._filter_sigma).to(image.device)
        self._validated = True

    @classmethod
    def _do_pad(cls, images: list[torch.Tensor], remainder: torch.Tensor) -> list[torch.Tensor]:
        """Pad images

        Parameters
        ----------
        images
            Images to pad (N,C,H,W)
        remainder
            Remaining images to pad (C,H,W)

        Returns

View on GitHub (pinned to f530cb7508)

Solutions

Switch the loss to 'ssim' as the message advises.
Or increase the model's output size above the MS-SSIM threshold (>=176px comfortably).
If a custom small model is required, use a different loss (mae/mse/lpips).

Example fix

# train config
# before
loss_function = ms_ssim  # output size 64px -> FaceswapError
# after
loss_function = ssim

Defensive patterns

Strategy: validation

Validate before calling

MIN_OUTPUT_PX = 176
assert model_output_size >= MIN_OUTPUT_PX or config.loss_function != 'ms_ssim', \
    'ms_ssim requires output >= 176px; use ssim'

Try / catch

try:
    loss = MSSIMLoss(...)
    loss(sample_batch)  # trigger validation at setup, not mid-epoch
except FaceswapError as err:
    if 'MS-SSIM' in str(err):
        loss = SSIMLoss(...)
    else:
        raise

Prevention

Pair ms_ssim only with models outputting >=176px.
Warm up the loss with a dummy batch during model build to fail fast.
Heed the 176px warning log — it precedes the hard failure.

When it happens

Trigger: Training a model whose output size is very small (far below 176px) with loss_function=ms_ssim; custom models with tiny output dimensions hitting MSSIM's first batch validation.

Common situations: Low-resolution experimental model configurations; users preferring MS-SSIM accuracy on small-output architectures where it is mathematically unsupported.

Related errors

AI-assisted analysis of deepfakes/faceswap@f530cb7508 (2026-08-15). Data as JSON: /api/errors/c71aa6b40883b8d7. Report an issue: GitHub.