{"record":{"id":"9753408e793c9b4b","repo":"deepfakes/faceswap","slug":"you-have-selected-the-mask-type-self-args-mask","errorCode":null,"errorMessage":"You have selected the Mask Type `{self._args.mask_type}` but at least one face does not have this mask stored in the Alignments File.\\nYou should generate the required masks with the Mask Tool or set the Mask Type option to an existing Mask Type.\\nA summary of existing masks is as follows:\\nTotal faces: {self._alignments.faces_count}, Masks: {self._alignments.mask_summary}","messagePattern":"You have selected the Mask Type `(.+?)` but at least one face does not have this mask stored in the Alignments File\\.\\\\nYou should generate the required masks with the Mask Tool or set the Mask Type option to an existing Mask Type\\.\\\\nA summary of existing masks is as follows:\\\\nTotal faces: (.+?), Masks: (.+?)","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"error","filePath":"scripts/convert.py","lineNumber":188,"sourceCode":"            raise FaceswapError(\"Output as video selected, but using frames as input. You must \"\n                                \"provide a reference video ('-ref', '--reference-video').\")\n\n        if (self._args.on_the_fly and\n                self._args.mask_type not in (\"none\", \"extended\", \"components\")):\n            logger.warning(\"You have selected an incompatible mask type ('%s') for On-The-Fly \"\n                           \"conversion. Switching to 'extended'\", self._args.mask_type)\n            self._args.mask_type = \"extended\"\n\n        if (not self._args.on_the_fly and\n                self._args.mask_type not in (\"none\", \"predicted\", \"extended\", \"components\") and\n                not self._alignments.mask_is_valid(self._args.mask_type)):\n            msg = (f\"You have selected the Mask Type `{self._args.mask_type}` but at least one \"\n                   \"face does not have this mask stored in the Alignments File.\\nYou should \"\n                   \"generate the required masks with the Mask Tool or set the Mask Type option to \"\n                   \"an existing Mask Type.\\nA summary of existing masks is as follows:\\nTotal \"\n                   f\"faces: {self._alignments.faces_count}, \"\n                   f\"Masks: {self._alignments.mask_summary}\")\n            raise FaceswapError(msg)\n\n        if self._args.mask_type == \"predicted\" and not self._predictor.has_predicted_mask:\n            available_masks = [k for k, v in self._alignments.mask_summary.items()\n                               if k != \"none\" and v == self._alignments.faces_count]\n            if not available_masks:\n                msg = (\"Predicted Mask selected, but the model was not trained with a mask and no \"\n                       \"masks are stored in the Alignments File.\\nYou should generate the \"\n                       \"required masks with the Mask Tool or set the Mask Type to `none`.\")\n                raise FaceswapError(msg)\n            mask_type = available_masks[0]\n            logger.warning(\"Predicted Mask selected, but the model was not trained with a \"\n                           \"mask. Selecting first available mask: '%s'\", mask_type)\n            self._args.mask_type = mask_type\n\n    def _add_queues(self) -> None:\n        \"\"\"Add the queues for in, patch and out.\"\"\"\n        logger.debug(\"Adding queues. Queue size: %s\", self._queue_size)\n        for qname in (\"convert_in\", \"convert_out\", \"patch\"):","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/scripts/convert.py#L170-L206","documentation":"FaceswapError raised in Convert._check_output_args when a non-built-in mask type is selected, on-the-fly conversion is off, and the alignments file reports that at least one face lacks that stored mask (alignments.mask_is_valid returns False). Built-ins none/predicted/extended/components bypass the check. The message includes a summary of masks that do exist to guide the fix.","triggerScenarios":"Running convert with -mask_type <custom> (e.g. vgg_clear, dfl_x_hybrid) where the alignments file has no (or incomplete) stored masks of that type. The mask summary in the message shows counts per mask type.","commonSituations":"User skips the mask job during extraction, extracts with a different mask set, or points convert at an alignments file from another project.","solutions":["Run the Mask tool (tools.py mask) with the missing mask type against the frames/alignments to generate and store it","Or set -mask_type to one shown with full coverage in the error's mask summary (count == total faces)","Or use a built-in option: none, extended, or components"],"exampleFix":"# before\npython faceswap.py convert ... -mask_type vgg_clear\n# error: masks summary shows vgg_clear: 0\n\n# after - generate the mask first\npython tools.py mask -i /data/frames -a /data/alignments.fsa \\\n    -M vgg_clear --process all\npython faceswap.py convert ... -mask_type vgg_clear","handlingStrategy":"validation","validationCode":"if args.mask_type not in (\"none\", \"predicted\", \"extended\", \"components\"):\n    summary = alignments.mask_summary\n    if summary.get(args.mask_type, 0) != alignments.faces_count:\n        raise SystemExit(\n            f\"mask '{args.mask_type}' incomplete: {summary.get(args.mask_type, 0)}/\"\n            f\"{alignments.faces_count}; run tools.py mask first\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run the mask job for every mask type you plan to convert with before starting convert","Inspect alignments.mask_summary (via the error message) to confirm full coverage"],"tags":["faceswap","convert","mask","alignments"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}