{"record":{"id":"712f973cf7172e49","repo":"deepfakes/faceswap","slug":"the-images-to-be-sorted-do-not-contain-alignment-d","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"error","filePath":"tools/sort/sort_methods.py","lineNumber":749,"sourceCode":"        to pull identity information from the PNG metadata. If not available, pulls the information\n        from the Identity plugin and stores in the PNG header for future use\n\n        Parameters\n        ----------\n        filename\n            The filename of the currently processing image\n        image\n            A face image loaded from disk or ``None``\n        alignments\n            The alignments dictionary for the aligned face or ``None``\n        \"\"\"\n        # pylint:disable=duplicate-code\n        if not alignments:\n            msg = (\"The images to be sorted do not contain alignment data. Images must have \"\n                   \"been generated by Faceswap's Extract process.\\nIf you are sorting an \"\n                   \"older face set, then you should re-extract the faces from your source \"\n                   \"alignments file to generate this data.\")\n            raise FaceswapError(msg)\n\n        if self._plugin_thread.error_state.has_error:\n            self._plugin_thread.error_state.re_raise()\n\n        self._count_seen += 1\n        if self._score_from_header(filename, alignments):\n            self._handle_plugin()\n            return\n\n        if not self._plugin_thread.is_alive():\n            logger.debug(\"Starting Identity plugin\")\n            self._runner = self._plugin()\n            self._plugin_thread.start()\n\n        self._alignment_queue.put((filename, alignments))\n\n        face = DetectedFace(left=alignments.x,  # Only include required items\n                            width=alignments.w,","sourceCodeStart":731,"sourceCodeEnd":767,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/tools/sort/sort_methods.py#L731-L767","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-extract the faces from the source frames with the current Faceswap extract so PNGs embed alignment metadata, then re-run sort.","If sorting an older Faceswap face set, re-extract from the original alignments file as the message suggests.","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."],"exampleFix":"# before\npython tools.py sort -t identity -i faces/\n# FaceswapError: ... do not contain alignment data ...\n\n# after\npython scripts/extract.py -i frames/ -o faces_fresh/\npython tools.py sort -t identity -i faces_fresh/","handlingStrategy":"validation","validationCode":"import os\nfrom lib.image import read_image_meta\n\ndef folder_has_alignment_data(folder: str) -> bool:\n    pngs = [f for f in os.listdir(folder) if f.lower().endswith(\".png\")]\n    if not pngs:\n        return False\n    meta = read_image_meta(os.path.join(folder, pngs[0]))\n    return meta.get(\"itxt\", {}).get(\"alignments\") is not None","typeGuard":null,"tryCatchPattern":"from lib.exceptions import FaceswapError\ntry:\n    sorter.sort()\nexcept FaceswapError as err:\n    if \"alignment data\" in str(err):\n        raise SystemExit(\"Re-extract faces with Faceswap before identity sort\") from err\n    raise","preventionTips":["Only run metadata-dependent sorts on folders produced by the same Faceswap version's extract.","Never post-process extracted PNGs with tools that rewrite metadata.","Sample-check one PNG's itxt metadata before batch sorting."],"tags":["faceswap","sort","metadata","extract","identity"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}