deepfakes/faceswap · error · FaceswapError

The images to be sorted do not contain alignment data. Image

Error message

The images to be sorted do not contain alignment data. Images must have been generated by Faceswap's Extract process.\nIf you are sorting an older face set, then you should re-extract the faces from your source alignments file to generate this data.

What it means

Sort tool (identity/similarity path in sort_methods.py): the current image's alignments metadata is falsy, meaning the PNG carried no Faceswap alignment data (the itxt metadata is absent or null). Identity/similarity sorting needs the stored face information, so processing aborts with guidance to re-extract.

Source

Thrown at tools/sort/sort_methods.py:749

        to pull identity information from the PNG metadata. If not available, pulls the information
        from the Identity plugin and stores in the PNG header for future use

        Parameters
        ----------
        filename
            The filename of the currently processing image
        image
            A face image loaded from disk or ``None``
        alignments
            The alignments dictionary for the aligned face or ``None``
        """
        # pylint:disable=duplicate-code
        if not alignments:
            msg = ("The images to be sorted do not contain alignment data. Images must have "
                   "been generated by Faceswap's Extract process.\nIf you are sorting an "
                   "older face set, then you should re-extract the faces from your source "
                   "alignments file to generate this data.")
            raise FaceswapError(msg)

        if self._plugin_thread.error_state.has_error:
            self._plugin_thread.error_state.re_raise()

        self._count_seen += 1
        if self._score_from_header(filename, alignments):
            self._handle_plugin()
            return

        if not self._plugin_thread.is_alive():
            logger.debug("Starting Identity plugin")
            self._runner = self._plugin()
            self._plugin_thread.start()

        self._alignment_queue.put((filename, alignments))

        face = DetectedFace(left=alignments.x,  # Only include required items
                            width=alignments.w,

View on GitHub (pinned to f530cb7508)

Solutions

1. Re-extract the faces from the source frames with the current Faceswap extract so PNGs embed alignment metadata, then re-run sort.
2. If sorting an older Faceswap face set, re-extract from the original alignments file as the message suggests.
3. Remove non-Faceswap images from the input folder before metadata-dependent sorts; use a sort method that does not need metadata (e.g. blur, face-size) if re-extraction is impossible.

Example fix

# before
python tools.py sort -t identity -i faces/
# FaceswapError: ... do not contain alignment data ...

# after
python scripts/extract.py -i frames/ -o faces_fresh/
python tools.py sort -t identity -i faces_fresh/

import os
from lib.image import read_image_meta

def folder_has_alignment_data(folder: str) -> bool:
    pngs = [f for f in os.listdir(folder) if f.lower().endswith(".png")]
    if not pngs:
        return False
    meta = read_image_meta(os.path.join(folder, pngs[0]))
    return meta.get("itxt", {}).get("alignments") is not None

from lib.exceptions import FaceswapError
try:
    sorter.sort()
except FaceswapError as err:
    if "alignment data" in str(err):
        raise SystemExit("Re-extract faces with Faceswap before identity sort") from err
    raise

When it happens

Trigger: Running `python tools.py sort -t identity` (or another metadata-dependent sort/group) over a folder containing images not produced by Faceswap's extract process — e.g. downloaded face sets, faces re-saved by editors that strip PNG metadata, or faces extracted by older versions predating metadata embedding.

Common situations: Sorting a celebrity face set scraped from the web; images processed through tools that re-encode PNGs; pre-metadata-era Faceswap extractions; mixing third-party aligned faces into the folder.

Related errors

• Aligned directory is empty, no faces will be converted!
• The images to be sorted do not contain alignment data. Image
• Video file '{self._video_file}' cannot be processed. Missing
• No fps, input or reference video was supplied, hence it's no
• Landmark based masks cannot be created for {self._landmark_t

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