deepfakes/faceswap · error · FaceswapError

Unhandled job: {self._args.job}. This is a bug. Please repor

Error message

Unhandled job: {self._args.job}. This is a bug. Please report to the developers

What it means

Internal invariant in the Alignments tool's file-location resolution: self._args.job is not one of the handled jobs (the branches above cover the normal jobs plus batch mode over a faces dir). Reaching the else means the job dispatcher and the location resolver got out of sync — a developer bug, not a user-input problem.

Source

Thrown at tools/alignments/alignments.py:195

        elif job in self._requires_frames:  # Jobs that require a frames folder
            retval = self._get_frames_locations()

        elif job in self._requires_faces and job not in self._requires_frames:
            # Jobs that require faces as input
            faces = [os.path.join(self._args.faces_dir, folder)
                     for folder in os.listdir(self._args.faces_dir)
                     if os.path.isdir(os.path.join(self._args.faces_dir, folder))]
            if not faces:
                logger.error("No folders found in '%s'", self._args.faces_dir)
                sys.exit(1)

            retval = {"faces_dir": faces,
                      "frames_dir": [None for _ in range(len(faces))],
                      "alignments_file": [None for _ in range(len(faces))]}
            logger.info("Batch mode selected. Processing faces: %s",
                        [os.path.basename(folder) for folder in faces])
        else:
            raise FaceswapError(f"Unhandled job: {self._args.job}. This is a bug. Please report "
                                "to the developers")

        logger.debug("File locations: %s", retval)
        return retval

    @staticmethod
    def _run_process(arguments) -> None:
        """ The alignements tool process to be run in a spawned process.

        In some instances, batch-mode memory leaks. Launching each job in a separate process
        prevents this leak.

        Parameters
        ----------
        arguments: :class:`argparse.Namespace`
            The :mod:`argparse` arguments to be used for the given job
        """
        logger.debug("Starting process: (arguments: %s)", arguments)

View on GitHub (pinned to f530cb7508)

Solutions

1. If you are a plain user, report the issue to the Faceswap developers with the exact command line and version (`python tools.py alignments -h` output).
2. If you maintain a fork, add a matching branch for the new job in _get_locations or route it through the batch-mode path.
3. Retry with a canonical job name from `python tools.py alignments -h`.

VALID_JOBS = {"extract", "sort", "multi-as-one"}  # adapt from `tools.py alignments -h`
def is_supported_job(job: str) -> bool:
    return job in VALID_JOBS

def assert_known_alignments_job(job: str) -> None:
    """Narrow the job string to the set _get_locations handles."""
    handled = {...}  # mirror the branches in tools/alignments/alignments.py
    assert job in handled, f"Unsupported alignments job: {job}"

from lib.exceptions import FaceswapError
try:
    locs = get_locations(arguments)
except FaceswapError as err:
    if "Unhandled job" in str(err):
        # developer bug: file upstream with command line + version
        ...

When it happens

Trigger: Passing an alignments job string that the CLI accepted but _get_locations does not branch on, or a new job added to the parser without a matching branch here. Not reachable through documented user flags on a released version.

Common situations: Local modifications/forks adding a job to the arg parser but not to this resolver; passing a job alias that only the GUI understands; version skew after a partial update.

Related errors

• There is a mismatch between the number of frames found in th
• The given shape {shape} is not valid. Valid shapes: {list(sh
• Dictionary keys {sorted(inbound)} should be a subset of data
• You have selected the mask type '{mask_type}' but at least o
• You have selected the Mask Type `{self._args.mask_type}` but

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