deepfakes/faceswap · error · FaceswapError

There should be 1 state file in your model folder. {len(stat

Error message

There should be 1 state file in your model folder. {len(state_files)} were found.

What it means

Raised by the convert process when the model folder does not contain exactly one '<name>_state.json' file. The state file stores which trainer (model plugin, e.g. 'original' or 'dfl-sae') produced the model, and convert needs this single file to load the correct model architecture. Zero state files means you pointed convert at a folder that was never trained in; two or more means multiple models' state files coexist in one folder.

Source

Thrown at scripts/convert.py:866

    def _get_model_name(self, model_dir: str) -> str:
        """Return the name of the Faceswap model used.

        Retrieve the name of the model from the model's state file.

        Parameters
        ----------
        model_dir
            The folder that contains the trained Faceswap model

        Returns
        -------
        The name of the Faceswap model being used.
        """
        state_files = [fname for fname in os.listdir(str(model_dir))
                       if fname.endswith("_state.json")]
        if len(state_files) != 1:
            raise FaceswapError("There should be 1 state file in your model folder. "
                                f"{len(state_files)} were found.")
        state_file = os.path.join(str(model_dir), state_files[0])

        state = self._serializer.load(state_file)
        trainer = state.get("name", None)

        if not trainer:
            raise FaceswapError("Trainer name could not be read from state file.")
        logger.debug("Trainer from state file: '%s'", trainer)
        return trainer

    def launch(self, load_queue: EventQueue) -> None:
        """Launch the prediction process in a background thread.

        Starts the prediction thread and returns the thread.

        Parameters
        ----------

View on GitHub (pinned to f530cb7508)

Solutions

Run convert with the exact folder that was used for training: `python scripts/convert.py -m /path/to/model` and verify with `ls /path/to/model/*_state.json` that exactly one file exists.
If two or more *_state.json files exist, move the stale one(s) (from previous experiments) out of the folder, keeping only the state file matching the model .h5/.keras weights you want to convert with.
If zero state files exist, the folder is not a trained Faceswap model folder — retrain into it or point --model-dir at the real training output folder.
If the state file was lost (e.g. partial copy), retrain briefly or restore it from a backup; convert cannot infer the trainer without it.

Example fix

# before
python scripts/convert.py -i in/ -o out/ -a aligned/ -m ~/faceswap/models   # folder holds 2 state files

# after
ls ~/faceswap/models/*_state.json
# move stale one out:
mv ~/faceswap/models/original_state.json ~/backup/
python scripts/convert.py -i in/ -o out/ -a aligned/ -m ~/faceswap/models

Defensive patterns

Strategy: validation

Validate before calling

import os, glob

def validate_model_dir(model_dir: str) -> str:
    state_files = [f for f in os.listdir(model_dir) if f.endswith("_state.json")]
    if len(state_files) != 1:
        raise SystemExit(
            f"Expected exactly 1 *_state.json in {model_dir}, found {len(state_files)}: {state_files}")
    return os.path.join(model_dir, state_files[0])

Try / catch

from lib.exceptions import FaceswapError
try:
    trainer = get_trainer(model_dir)
except FaceswapError as err:
    print(f"Model folder invalid: {err}")
    # list candidates to help the user pick
    print([f for f in os.listdir(model_dir) if f.endswith("_state.json")])
    raise SystemExit(1)

Prevention

One dedicated folder per trained model; never train a second model into the same folder.
Script a preflight check that globs *_state.json and asserts exactly one match before launching convert.
Keep backups of the model folder including the state file alongside the weights.

When it happens

Trigger: Calling `python scripts/convert.py -m <model_dir>` where os.listdir(model_dir) returns either 0 or >= 2 filenames ending in '_state.json'. Happens when the model dir is empty/wrong, when a second model was trained into the same folder, or when a state file was manually copied in.

Common situations: Typos in the --model-dir argument; re-using a training folder for a different model architecture without cleaning it; copying model files between machines and accidentally duplicating state files; pointing at the parent folder instead of the actual model subfolder.

Related errors

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