Unity-Technologies/ml-agents · error · TrainerConfigError

The option {} was specified in your YAML file, but is invali

Error message

The option {} was specified in your YAML file, but is invalid.

What it means

Raised in TrainerSettings.from_argparse (run trainer settings parsing) when a key loaded from the user's YAML config file does not correspond to any recognized setting in the argparse-based settings structure. It is a generic config-key guard: the option name itself is at fault — usually a typo, an option from an incompatible ml-agents version, or an option placed in the wrong section of the YAML file.

Source

Thrown at ml-agents/mlagents/trainers/settings.py:923

        # Load YAML
        configured_dict: Dict[str, Any] = {
            "checkpoint_settings": {},
            "env_settings": {},
            "engine_settings": {},
            "torch_settings": {},
        }
        _require_all_behaviors = True
        if config_path is not None:
            configured_dict.update(load_config(config_path))
        else:
            # If we're not loading from a file, we don't require all behavior names to be specified.
            _require_all_behaviors = False

        # Use the YAML file values for all values not specified in the CLI.
        for key in configured_dict.keys():
            # Detect bad config options
            if key not in attr.fields_dict(RunOptions):
                raise TrainerConfigError(
                    "The option {} was specified in your YAML file, but is invalid.".format(
                        key
                    )
                )

        # Override with CLI args
        # Keep deprecated --load working, TODO: remove
        argparse_args["resume"] = argparse_args["resume"] or argparse_args["load_model"]

        for key, val in argparse_args.items():
            if key in DetectDefault.non_default_args:
                if key in attr.fields_dict(CheckpointSettings):
                    configured_dict["checkpoint_settings"][key] = val
                elif key in attr.fields_dict(EnvironmentSettings):
                    configured_dict["env_settings"][key] = val
                elif key in attr.fields_dict(EngineSettings):
                    configured_dict["engine_settings"][key] = val
                elif key in attr.fields_dict(TorchSettings):

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Check the highlighted option name for typos against the official ml-agents configuration documentation for your version
2. Remove or rename options that were renamed or removed in the ml-agents version you are running
3. Verify the option is placed under the correct top-level section (e.g. checkpoint_settings, env_settings, engine_settings) rather than an arbitrary location

When it happens

Trigger: Thrown at ml-agents/mlagents/trainers/settings.py:923 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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