deepfakes/faceswap · error · FaceswapError

You have selected the mask type '{mask_type}' but at least o

Error message

You have selected the mask type '{mask_type}' but at least one face does not contain the selected mask.\nThe face that failed was: '{filename}'\n{msg}

What it means

Thrown by the training DataSet when the mask type chosen in the training configuration does not exist for at least one face in the alignments data. Faceswap stores masks inside the faceswap alignments file (produced by the extraction pipeline), so this error means the requested mask was never generated (or was generated only for some faces) for the offending face.

Source

Thrown at lib/training/data/data_set.py:169

        masks
            The list of mask keys that exist for the currently processing face
        mask_type
            The requested mask type
        filename
            The name of the extracted face file currently being processed

        Raises
        ------
        FaceswapError
            If the requested mask type is not available an error is returned along with a list
            of available masks
        """
        exist_masks = masks + list(self._lm_masks)
        if mask_type in exist_masks:
            return
        msg = (f"The masks that exist for this face are: {exist_masks}" if exist_masks
               else "No masks exist for this face")
        raise FaceswapError(
            f"You have selected the mask type '{mask_type}' but at least one "
            "face does not contain the selected mask.\n"
            f"The face that failed was: '{filename}'\n{msg}")

    def _get_landmarks_mask(self,
                            mask_type: T.Literal["face", "face_extended", "eye", "mouth"],
                            aligned: AlignedFace) -> npt.NDArray[np.uint8]:
        """Obtain a landmarks based mask directly from the aligned face object

        Parameters
        ----------
        mask_type
            The type of landmarks based mask to obtain
        aligned
            The aligned face object to obtain the mask from

        Returns
        -------

View on GitHub (pinned to f530cb7508)

Solutions

Set the training config (go to 'Train' config in the GUI or edit the training config file) Mask > mask_type to a mask that is listed in the error message as existing for the faces (or to 'none' to train without a mask).
If the mask you want is missing, generate it by re-running the mask job: faceswap mask -a <alignments> -i <faces folder> -M <mask_type> before training.
Re-run alignment/extraction with the mask plugin enabled so all faces carry the mask.
If only a few faces fail (the filename is printed), regenerate masks for that subset or remove the offending face from the training folder.

Example fix

# before (training config)
[mask.mask_type] = bisenet-fp-head  # not present in alignments

# after: use a mask that exists (error message lists them)
[mask.mask_type] = vgg-clear
# or regenerate the missing mask first:
# faceswap mask -i faces/ -a faces/alignments.fsa -M bisenet-fp --include-hair

Defensive patterns

Strategy: validation

Validate before calling

from lib.serializer import get_serializer
from lib.align.alignments import AlignmentFileCache  # faceswap's alignments access
# Easiest pre-check: the CLI/GUI 'mask' job lists existing masks, or:
# faceswap mask -a alignments.fsa -i faces/ (shows what exists)
# Programmatically, confirm the chosen mask exists for every face before training:
import lib.align.animations  # noqa ensure loaded
from lib.align.aligned_face import AlignedFace
# pseudo: iterate alignments and check mask storage keys
# for face in alignments.faces: assert mask_type in face.mask.stored_masks

Type guard

def mask_exists(mask_type: str, stored_mask_types: list[str], lm_masks: tuple[str,...] = ("face","face_extended","eye","mouth")) -> bool:
    return mask_type in stored_mask_types or mask_type in lm_masks

Prevention

Always generate masks in the extraction pipeline with the same mask plugin you will train with.
Keep the training config's mask_type in sync with the masks actually stored in your alignments file.
After re-extraction, re-check available masks with the 'mask' job before launching training.

When it happens

Trigger: Starting a training session with cfg.Mask.mask_type set to a mask (e.g. 'bisenet-fp', 'vgg-clear', 'custom') that is not present in the masks list of at least one aligned face. The check runs per-face via the mask validation routine in lib/training/data/data_set.py during dataset build, before training begins.

Common situations: User ran extraction/masking with one mask plugin but configured training to use a different one; user re-extracted faces or deleted alignments without regenerating masks; older alignments files created before a mask plugin existed; using a landmarks-based mask name that is not in self._lm_masks ('face', 'face_extended', 'eye', 'mouth').

Related errors

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