{"record":{"id":"4ef1d51bc58d2de7","repo":"deepfakes/faceswap","slug":"aligned-directory-is-empty-no-faces-will-be-conve","errorCode":null,"errorMessage":"Aligned directory is empty, no faces will be converted!","messagePattern":"Aligned directory is empty, no faces will be converted!","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"critical","filePath":"scripts/convert.py","lineNumber":1170,"sourceCode":"        if not os.path.isdir(input_aligned_dir):\n            logger.warning(\"Aligned directory not found. All faces listed in the \"\n                           \"alignments file will be converted\")\n            return retval\n\n        filelist = get_image_paths(input_aligned_dir)\n        for fullpath, metadata in tqdm(read_image_meta_batch(filelist),\n                                       total=len(filelist),\n                                       desc=\"Reading Face Data\",\n                                       leave=False):\n            if \"itxt\" not in metadata or \"source\" not in metadata[\"itxt\"]:\n                logger.warning(\"Non-Faceswap extracted face found. Image skipped: '%s'\",\n                               fullpath)\n                continue\n            meta = metadata[\"itxt\"][\"source\"]\n            retval.setdefault(meta[\"source_filename\"], []).append(meta[\"face_index\"])\n\n        if not retval:\n            raise FaceswapError(\"Aligned directory is empty, no faces will be converted!\")\n        if len(retval) <= len(self._input_images) / 3:\n            logger.warning(\"Aligned directory contains far fewer images than the input \"\n                           \"directory, are you sure this is the right folder?\")\n        return retval\n\n\n__all__ = get_module_objects(__name__)\n","sourceCodeStart":1152,"sourceCodeEnd":1178,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/scripts/convert.py#L1152-L1178","documentation":"Raised while convert builds its face-alignment lookup: after scanning every image in the aligned faces folder, not one contained Faceswap metadata (PNG 'itxt' chunk with a 'source' dict). Convert maps each aligned face back to its source frame via this embedded metadata; an empty map means no faces can be swapped.","triggerScenarios":"Running convert with `--aligned-dir` pointing at a folder whose images either (a) are not PNGs from Faceswap's extract process, or (b) had their metadata stripped (re-saved/resized/re-exported by another tool). Every image hit the 'Non-Faceswap extracted face found' skip branch, leaving the mapping empty.","commonSituations":"Pointing --aligned-dir at the raw frames folder or the output folder instead of the extract faces folder; running images through an editor/batch resizer that drops PNG text chunks; using faces extracted by an older version or third-party extractor that writes no itxt metadata.","solutions":["Point --aligned-dir at the folder of aligned faces produced by `python scripts/extract.py` for this specific source set.","If the faces were re-saved by another tool, re-run extract (or re-emit the aligned faces from the alignments file with the Alignment tool) so the PNG itxt metadata is regenerated.","Verify metadata presence before converting: `python -c \"from lib.image import read_image_meta; print(read_image_meta('aligned/face_00000.png'))\"` and confirm itxt/source exist.","Ensure the alignments file used for extract matches the frames you are converting."],"exampleFix":"# before\npython scripts/convert.py -i frames/ -o out/ -a frames/ -m model/   # -a points at frames, not aligned faces\n\n# after\npython scripts/extract.py -i frames/ -o aligned_faces/\npython scripts/convert.py -i frames/ -o out/ -a aligned_faces/ -m model/","handlingStrategy":"validation","validationCode":"import os\nfrom lib.image import read_image_meta\n\ndef aligned_dir_has_faceswap_faces(aligned_dir: str) -> bool:\n    pngs = [f for f in os.listdir(aligned_dir) if f.lower().endswith(\".png\")]\n    if not pngs:\n        return False\n    meta = read_image_meta(os.path.join(aligned_dir, pngs[0]))\n    return \"itxt\" in meta and \"source\" in meta[\"itxt\"]","typeGuard":null,"tryCatchPattern":"from lib.exceptions import FaceswapError\ntry:\n    mappings = build_alignments_map(aligned_dir)\nexcept FaceswapError as err:\n    if \"Aligned directory is empty\" in str(err):\n        raise SystemExit(\"Re-extract faces with Faceswap before converting\") from err\n    raise","preventionTips":["Always generate the aligned folder with the same Faceswap version that will convert.","Never re-save/re-compress extracted face PNGs with external tools before convert.","Wire extract -> convert in one pipeline so the aligned folder is always fresh."],"tags":["faceswap","convert","metadata","extract","configuration"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}