What causes "Aligned directory is empty, no faces will be converted!" in deepfakes/faceswap?

Point --aligned-dir at the folder of aligned faces produced by `python scripts/extract.py` for this specific source set.

deepfakes/faceswap · critical · FaceswapError

Aligned directory is empty, no faces will be converted!

Error message

Aligned directory is empty, no faces will be converted!

What it means

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.

Source

Thrown at scripts/convert.py:1170

        if not os.path.isdir(input_aligned_dir):
            logger.warning("Aligned directory not found. All faces listed in the "
                           "alignments file will be converted")
            return retval

        filelist = get_image_paths(input_aligned_dir)
        for fullpath, metadata in tqdm(read_image_meta_batch(filelist),
                                       total=len(filelist),
                                       desc="Reading Face Data",
                                       leave=False):
            if "itxt" not in metadata or "source" not in metadata["itxt"]:
                logger.warning("Non-Faceswap extracted face found. Image skipped: '%s'",
                               fullpath)
                continue
            meta = metadata["itxt"]["source"]
            retval.setdefault(meta["source_filename"], []).append(meta["face_index"])

        if not retval:
            raise FaceswapError("Aligned directory is empty, no faces will be converted!")
        if len(retval) <= len(self._input_images) / 3:
            logger.warning("Aligned directory contains far fewer images than the input "
                           "directory, are you sure this is the right folder?")
        return retval


__all__ = get_module_objects(__name__)

View on GitHub (pinned to f530cb7508)

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.

Example fix

# before
python scripts/convert.py -i frames/ -o out/ -a frames/ -m model/   # -a points at frames, not aligned faces

# after
python scripts/extract.py -i frames/ -o aligned_faces/
python scripts/convert.py -i frames/ -o out/ -a aligned_faces/ -m model/

Defensive patterns

Strategy: validation

Validate before calling

import os
from lib.image import read_image_meta

def aligned_dir_has_faceswap_faces(aligned_dir: str) -> bool:
    pngs = [f for f in os.listdir(aligned_dir) if f.lower().endswith(".png")]
    if not pngs:
        return False
    meta = read_image_meta(os.path.join(aligned_dir, pngs[0]))
    return "itxt" in meta and "source" in meta["itxt"]

Try / catch

from lib.exceptions import FaceswapError
try:
    mappings = build_alignments_map(aligned_dir)
except FaceswapError as err:
    if "Aligned directory is empty" in str(err):
        raise SystemExit("Re-extract faces with Faceswap before converting") from err
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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