Unity-Technologies/ml-agents · error · TrainerConfigError

There was an error decoding Config file from {config_path}.

Error message

There was an error decoding Config file from {config_path}. Make sure your file is save using UTF-8

What it means

load_config reads the trainer config YAML as UTF-8 text; a UnicodeDecodeError means the bytes are not valid UTF-8 (e.g. the file was saved in Latin-1 or contains a UTF-8 BOM/invisible characters), so it raises TrainerConfigError asking you to re-save as UTF-8.

Source

Thrown at ml-agents/mlagents/trainers/cli_utils.py:328

    torch_conf.add_argument(
        "--torch-device",
        default=None,
        dest="device",
        action=DetectDefault,
        help='Settings for the default torch.device used in training, for example, "cpu", "cuda", or "cuda:0"',
    )
    return argparser


def load_config(config_path: str) -> Dict[str, Any]:
    try:
        with open(config_path) as data_file:
            return _load_config(data_file)
    except OSError:
        abs_path = os.path.abspath(config_path)
        raise TrainerConfigError(f"Config file could not be found at {abs_path}.")
    except UnicodeDecodeError:
        raise TrainerConfigError(
            f"There was an error decoding Config file from {config_path}. "
            f"Make sure your file is save using UTF-8"
        )


def _load_config(fp: TextIO) -> Dict[str, Any]:
    """
    Load the yaml config from the file-like object.
    """
    try:
        return yaml.safe_load(fp)
    except yaml.parser.ParserError as e:
        raise TrainerConfigError(
            "Error parsing yaml file. Please check for formatting errors. "
            "A tool such as http://www.yamllint.com/ can be helpful with this."
        ) from e

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Re-save the YAML with UTF-8 encoding in your editor
2. Convert in place: iconv -f latin1 -t utf-8 config.yaml -o config_utf8.yaml
3. Remove/retype non-ASCII characters (smart quotes, em dashes) in the config

Example fix

// before
# config saved as ANSI/Latin-1
mlagents-learn config.yaml ...
// after
iconv -f WINDOWS-1252 -t UTF-8 config.yaml > config_utf8.yaml
mlagents-learn config_utf8.yaml ...

raw = open(config_path, 'rb').read()
try:
    raw.decode('utf-8')
except UnicodeDecodeError as e:
    raise SystemExit(f"{config_path} is not UTF-8: {e}; re-save the file as UTF-8")

try:
    config = load_config(config_path)
except TrainerConfigError as e:
    if 'decoding' in str(e):
        print(f"Re-save {config_path} as UTF-8")
    raise

When it happens

Trigger: Opening a config YAML edited in a non-UTF-8 editor or downloaded with a different encoding; the exception is raised during open/read in load_config (via main/from_argparse).

Common situations: Configs edited on Windows in Notepad with ANSI encoding, files with smart quotes or special characters pasted from docs, or YAML exported from Excel.

Related errors

• Error parsing yaml file. Please check for formatting errors.
• Config doesn't specify a trainer type. Please specify traine
• Config doesn't specify use_recurrent. Please specify true or
• Config file could not be found at {abs_path}.
• The option {key} was specified in your YAML file for {class_

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/511a81220d29a92e. Report an issue: GitHub.