deepfakes/faceswap · error · FaceswapError

You have selected the Mask Type `{self._args.mask_type}` but

Error message

You have selected the Mask Type `{self._args.mask_type}` but at least one face does not have this mask stored in the Alignments File.\nYou should generate the required masks with the Mask Tool or set the Mask Type option to an existing Mask Type.\nA summary of existing masks is as follows:\nTotal faces: {self._alignments.faces_count}, Masks: {self._alignments.mask_summary}

What it means

FaceswapError raised in Convert._check_output_args when a non-built-in mask type is selected, on-the-fly conversion is off, and the alignments file reports that at least one face lacks that stored mask (alignments.mask_is_valid returns False). Built-ins none/predicted/extended/components bypass the check. The message includes a summary of masks that do exist to guide the fix.

Source

Thrown at scripts/convert.py:188

            raise FaceswapError("Output as video selected, but using frames as input. You must "
                                "provide a reference video ('-ref', '--reference-video').")

        if (self._args.on_the_fly and
                self._args.mask_type not in ("none", "extended", "components")):
            logger.warning("You have selected an incompatible mask type ('%s') for On-The-Fly "
                           "conversion. Switching to 'extended'", self._args.mask_type)
            self._args.mask_type = "extended"

        if (not self._args.on_the_fly and
                self._args.mask_type not in ("none", "predicted", "extended", "components") and
                not self._alignments.mask_is_valid(self._args.mask_type)):
            msg = (f"You have selected the Mask Type `{self._args.mask_type}` but at least one "
                   "face does not have this mask stored in the Alignments File.\nYou should "
                   "generate the required masks with the Mask Tool or set the Mask Type option to "
                   "an existing Mask Type.\nA summary of existing masks is as follows:\nTotal "
                   f"faces: {self._alignments.faces_count}, "
                   f"Masks: {self._alignments.mask_summary}")
            raise FaceswapError(msg)

        if self._args.mask_type == "predicted" and not self._predictor.has_predicted_mask:
            available_masks = [k for k, v in self._alignments.mask_summary.items()
                               if k != "none" and v == self._alignments.faces_count]
            if not available_masks:
                msg = ("Predicted Mask selected, but the model was not trained with a mask and no "
                       "masks are stored in the Alignments File.\nYou should generate the "
                       "required masks with the Mask Tool or set the Mask Type to `none`.")
                raise FaceswapError(msg)
            mask_type = available_masks[0]
            logger.warning("Predicted Mask selected, but the model was not trained with a "
                           "mask. Selecting first available mask: '%s'", mask_type)
            self._args.mask_type = mask_type

    def _add_queues(self) -> None:
        """Add the queues for in, patch and out."""
        logger.debug("Adding queues. Queue size: %s", self._queue_size)
        for qname in ("convert_in", "convert_out", "patch"):

View on GitHub (pinned to f530cb7508)

Solutions

1. Run the Mask tool (tools.py mask) with the missing mask type against the frames/alignments to generate and store it
2. Or set -mask_type to one shown with full coverage in the error's mask summary (count == total faces)
3. Or use a built-in option: none, extended, or components

Example fix

# before
python faceswap.py convert ... -mask_type vgg_clear
# error: masks summary shows vgg_clear: 0

# after - generate the mask first
python tools.py mask -i /data/frames -a /data/alignments.fsa \
    -M vgg_clear --process all
python faceswap.py convert ... -mask_type vgg_clear

if args.mask_type not in ("none", "predicted", "extended", "components"):
    summary = alignments.mask_summary
    if summary.get(args.mask_type, 0) != alignments.faces_count:
        raise SystemExit(
            f"mask '{args.mask_type}' incomplete: {summary.get(args.mask_type, 0)}/"
            f"{alignments.faces_count}; run tools.py mask first")

When it happens

Trigger: Running convert with -mask_type <custom> (e.g. vgg_clear, dfl_x_hybrid) where the alignments file has no (or incomplete) stored masks of that type. The mask summary in the message shows counts per mask type.

Common situations: User skips the mask job during extraction, extracts with a different mask set, or points convert at an alignments file from another project.

Related errors

• Predicted Mask selected, but the model was not trained with
• You have selected the mask type '{mask_type}' but at least o
• Landmark based masks cannot be created for {self._landmark_t
• There is a mismatch between the number of frames found in th
• The given shape {shape} is not valid. Valid shapes: {list(sh

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