Unity-Technologies/ml-agents · error · TrainerConfigError

The option {key} was specified in your YAML file for {class_

Error message

The option {key} was specified in your YAML file for {class_type.__name__}, but is invalid.

What it means

TrainerConfigError raised by check_and_structure when a key in the trainer YAML config is not a recognized attrs field on the target settings class. ML-Agents strictly validates config keys against the attrs classes (TrainerSettings, PPOSettings, etc.) and rejects unknown options rather than silently ignoring them. Called for each key during structure()/strict_to_cls() config loading.

Source

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

import copy

from mlagents.trainers.cli_utils import StoreConfigFile, DetectDefault, parser
from mlagents.trainers.cli_utils import load_config
from mlagents.trainers.exception import TrainerConfigError, TrainerConfigWarning

from mlagents_envs import logging_util
from mlagents_envs.side_channel.environment_parameters_channel import (
    EnvironmentParametersChannel,
)
from mlagents.plugins import all_trainer_settings, all_trainer_types

logger = logging_util.get_logger(__name__)


def check_and_structure(key: str, value: Any, class_type: type) -> Any:
    attr_fields_dict = attr.fields_dict(class_type)
    if key not in attr_fields_dict:
        raise TrainerConfigError(
            f"The option {key} was specified in your YAML file for {class_type.__name__}, but is invalid."
        )
    # Apply cattr structure to the values
    return cattr.structure(value, attr_fields_dict[key].type)


def check_hyperparam_schedules(val: Dict, trainer_type: str) -> Dict:
    # Check if beta and epsilon are set. If not, set to match learning rate schedule.
    if trainer_type == "ppo" or trainer_type == "poca":
        if "beta_schedule" not in val.keys() and "learning_rate_schedule" in val.keys():
            val["beta_schedule"] = val["learning_rate_schedule"]
        if (
            "epsilon_schedule" not in val.keys()
            and "learning_rate_schedule" in val.keys()
        ):
            val["epsilon_schedule"] = val["learning_rate_schedule"]
    return val

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Check the spelling of the flagged key against the settings class in mlagents/trainers/settings.py (e.g. lambd, not lambda or lamda).
2. Move the option to the correct nesting level — many options belong under hyperparameters or network_settings, not the top level.
3. If upgrading from an older version, migrate removed/renamed options per the ML-Agents migration guide.
4. Run the config through the config validator (mlagents-learn will print which key/class failed) and delete or correct invalid keys.

Example fix

# before (SAC hyperparameters)
hyperparameters:
  learning_rate_schedule: constant
  buffer_size: 50000
  beta: 0.005   # PPO-only option
# after
hyperparameters:
  learning_rate_schedule: constant
  buffer_size: 50000

import yaml, attr
from mlagents.trainers.settings import TrainerSettings
raw = yaml.safe_load(open("config.yaml"))
valid = set(attr.fields_dict(TrainerSettings)) | set(attr.fields_dict(type(raw.get("hyperparameters", object))))
unknown = set(raw) - valid
if unknown:
    print(f"Unknown top-level options: {unknown}")

import attr
def keys_are_valid(d: dict, cls: type) -> bool:
    fields = set(attr.fields_dict(cls))
    return set(d) <= fields

from mlagents.trainers.exception import TrainerConfigError
try:
    settings = load_config("config.yaml")
except TrainerConfigError as e:
    logger.error(f"Fix config: {e}")
    raise SystemExit(1)

When it happens

Trigger: Any YAML key that doesn't match an attrs field name of the settings class — misspelled options (e.g. 'lamda' vs 'lambd'), options placed in the wrong section (e.g. beta under SAC hyperparameters), or options removed/renamed in a newer ML-Agents version.

Common situations: Old configs from ML-Agents 0.x used with the PyTorch release (renamed options like use_recurrent -> memory, summary_freq placement); typos like 'batchsize'; copying examples from outdated tutorials.

Related errors

• Unsupported config {d} for {t.__name__}.
• When using a recurrent network, memory size must be greater
• Action spaces with both continuous and discrete actions are
• The number of training areas that you have specified exceeds
• Can't use Behavior Type {behaviorType} without a model. Eith

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