{"record":{"id":"25428a1d4a65173a","repo":"deepfakes/faceswap","slug":"invalid-face-image-found-aborting-filename","errorCode":null,"errorMessage":"Invalid face image found. Aborting: '{filename}'","messagePattern":"Invalid face image found\\. Aborting: '(.+?)'","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"error","filePath":"lib/training/data/collate.py","lineNumber":163,"sourceCode":"\n    def _landmarks_from_header(self, meta: dict[str, T.Any], filename: str\n                               ) -> npt.NDArray[np.float32]:\n        \"\"\"Extract the landmarks from the PNG metadata.\n\n        Returns\n        -------\n        landmarks\n            The frame space landmarks for a face\n        filename\n            The name of the face image that we are loading landmarks for\n\n        Raises\n        ------\n        FaceswapError\n            If an invalid image is loaded or 68 point landmarks are not used\n        \"\"\"\n        if \"itxt\" not in meta or \"alignments\" not in meta[\"itxt\"]:\n            raise FaceswapError(f\"Invalid face image found. Aborting: '{filename}'\")\n\n        retval = np.array(meta[\"itxt\"][\"alignments\"][\"landmarks_xy\"], dtype=np.float32)\n        if LandmarkType.from_shape(retval.shape) != LandmarkType.LM_2D_68:\n            raise FaceswapError(\"68 Point facial Landmarks are required for Warp-to-\"\n                                f\"landmarks. The face that failed was: '{filename}'\")\n        return retval\n\n    def _align_points(self, points: npt.NDArray[np.float32]) -> npt.NDArray[np.float32]:\n        \"\"\"Normalize and align the landmarks to model input size/coverage/offset\n\n        points\n        ------\n        The (N, 68, 2) landmark points to align\n\n        Returns\n        -------\n        The landmark points aligned to model input\n        \"\"\"","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/lib/training/data/collate.py#L145-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"Feeding third-party cropped datasets into training; images edited/compressed after extraction; copy pipelines that strip metadata.","solutions":["Use faceswap's own extract output (faces contain embedded alignments) for warp-to-landmarks training.","Re-run extraction on the source frames to regenerate metadata-embedded face PNGs.","Avoid re-saving/editing extracted faces with tools that strip PNG metadata."],"exampleFix":"from lib.image import read_image_meta\n\n# before: train on arbitrary crops\n# -> FaceswapError: Invalid face image found. Aborting: 'face_001.png'\n\n# after: pre-validate dataset\nfor fn in face_files:\n    meta = read_image_meta(fn)\n    assert 'itxt' in meta and 'alignments' in meta['itxt'], f'{fn} lacks alignments; re-extract'","handlingStrategy":"validation","validationCode":"from lib.image import read_image_meta\n\ndef has_alignments(png_path: str) -> bool:\n    meta = read_image_meta(png_path)\n    return 'itxt' in meta and 'alignments' in meta['itxt']\n\nbad = [f for f in face_files if not has_alignments(f)]\nif bad:\n    raise SystemExit(f'{len(bad)} faces lack alignments metadata; re-extract first')","typeGuard":"def is_faceswap_face(png_path: str) -> bool:\n    try:\n        return has_alignments(png_path)\n    except Exception:\n        return False","tryCatchPattern":"try:\n    batch = collate(samples)\nexcept FaceswapError as err:\n    if 'Invalid face image' in str(err):\n        drop_offending_files_and_retry()  # error names the exact file\n    else:\n        raise","preventionTips":["Only use faces from faceswap's own extract output for warp-to-landmarks.","Do not re-save extracted faces with external tools (strips iTXt).","Pre-validate the whole faces folder before multi-hour training runs."],"tags":["training","metadata","alignments","png","dataset"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}