deepfakes/faceswap · error · FaceswapError

Invalid face image found. Aborting: '{filename}'

Error message

Invalid face image found. Aborting: '{filename}'

What it means

In warp-to-landmarks training, collate reads alignment metadata embedded in each face PNG's iTXt chunk. If the image has no 'itxt' metadata or the itxt lacks an 'alignments' key, the face was never processed by faceswap extraction (or metadata was stripped) and training aborts with this FaceswapError naming the file.

Source

Thrown at lib/training/data/collate.py:163

    def _landmarks_from_header(self, meta: dict[str, T.Any], filename: str
                               ) -> npt.NDArray[np.float32]:
        """Extract the landmarks from the PNG metadata.

        Returns
        -------
        landmarks
            The frame space landmarks for a face
        filename
            The name of the face image that we are loading landmarks for

        Raises
        ------
        FaceswapError
            If an invalid image is loaded or 68 point landmarks are not used
        """
        if "itxt" not in meta or "alignments" not in meta["itxt"]:
            raise FaceswapError(f"Invalid face image found. Aborting: '{filename}'")

        retval = np.array(meta["itxt"]["alignments"]["landmarks_xy"], dtype=np.float32)
        if LandmarkType.from_shape(retval.shape) != LandmarkType.LM_2D_68:
            raise FaceswapError("68 Point facial Landmarks are required for Warp-to-"
                                f"landmarks. The face that failed was: '{filename}'")
        return retval

    def _align_points(self, points: npt.NDArray[np.float32]) -> npt.NDArray[np.float32]:
        """Normalize and align the landmarks to model input size/coverage/offset

        points
        ------
        The (N, 68, 2) landmark points to align

        Returns
        -------
        The landmark points aligned to model input
        """

View on GitHub (pinned to f530cb7508)

Solutions

1. Use faceswap's own extract output (faces contain embedded alignments) for warp-to-landmarks training.
2. Re-run extraction on the source frames to regenerate metadata-embedded face PNGs.
3. Avoid re-saving/editing extracted faces with tools that strip PNG metadata.

Example fix

from lib.image import read_image_meta

# before: train on arbitrary crops
# -> FaceswapError: Invalid face image found. Aborting: 'face_001.png'

# after: pre-validate dataset
for fn in face_files:
    meta = read_image_meta(fn)
    assert 'itxt' in meta and 'alignments' in meta['itxt'], f'{fn} lacks alignments; re-extract'

from lib.image import read_image_meta

def has_alignments(png_path: str) -> bool:
    meta = read_image_meta(png_path)
    return 'itxt' in meta and 'alignments' in meta['itxt']

bad = [f for f in face_files if not has_alignments(f)]
if bad:
    raise SystemExit(f'{len(bad)} faces lack alignments metadata; re-extract first')

def is_faceswap_face(png_path: str) -> bool:
    try:
        return has_alignments(png_path)
    except Exception:
        return False

try:
    batch = collate(samples)
except FaceswapError as err:
    if 'Invalid face image' in str(err):
        drop_offending_files_and_retry()  # error names the exact file
    else:
        raise

When it happens

Trigger: Pointing a warp-to-landmarks trainer at raw face crops not produced by faceswap extract; images re-saved by tools that drop PNG text chunks; converting PNGs to another format and back, losing iTXt.

Common situations: Feeding third-party cropped datasets into training; images edited/compressed after extraction; copy pipelines that strip metadata.

Related errors

• 68 Point facial Landmarks are required for Warp-to-landmarks
• You have selected the mask type '{mask_type}' but at least o
• The images to be sorted do not contain alignment data. Image
• 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/25428a1d4a65173a. Report an issue: GitHub.