Unity-Technologies/ml-agents · error · TrainerConfigError

The behavior name {key} has not been specified in the traine

Error message

The behavior name {key} has not been specified in the trainer configuration. Please add an entry in the configuration file for {key}, or set default_settings.

What it means

The DefaultTrainerDict supplies defaults for behaviors not explicitly configured. When config_specified=True (a config file was provided) and default_override is unset, accessing an unlisted behavior name raises TrainerConfigError telling the user to add an entry or set default_settings.

Source

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

    class DefaultTrainerDict(collections.defaultdict):
        def __init__(self, *args):
            # Depending on how this is called, args may have the defaultdict
            # callable at the start of the list or not. In particular, unpickling
            # will pass [TrainerSettings].
            if args and args[0] == TrainerSettings:
                super().__init__(*args)
            else:
                super().__init__(TrainerSettings, *args)
            self._config_specified = True

        def set_config_specified(self, require_config_specified: bool) -> None:
            self._config_specified = require_config_specified

        def __missing__(self, key: Any) -> "TrainerSettings":
            if TrainerSettings.default_override is not None:
                self[key] = copy.deepcopy(TrainerSettings.default_override)
            elif self._config_specified:
                raise TrainerConfigError(
                    f"The behavior name {key} has not been specified in the trainer configuration. "
                    f"Please add an entry in the configuration file for {key}, or set default_settings."
                )
            else:
                logger.warning(
                    f"Behavior name {key} does not match any behaviors specified "
                    f"in the trainer configuration file. A default configuration will be used."
                )
                self[key] = TrainerSettings()
            return self[key]


# COMMAND LINE #########################################################################
@attr.s(auto_attribs=True)
class CheckpointSettings:
    run_id: str = parser.get_default("run_id")
    initialize_from: Optional[str] = parser.get_default("initialize_from")
    load_model: bool = parser.get_default("load_model")

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Add a top-level entry for the missing behavior name in the trainer config YAML.
2. Add a default_settings section so unlisted behaviors inherit defaults.
3. Match the behavior name exactly to the Behavior Name field in the Unity agent's Behavior Parameters.

Example fix

# before
BehaviorA:
  trainer_type: ppo
  ...
# after
default_settings:
  trainer_type: ppo
BehaviorA:
  trainer_type: ppo
  ...
BehaviorB:
  trainer_type: ppo

behaviors = collect_behavior_names_from_env()
missing = [b for b in behaviors if b not in yaml_cfg and 'default_settings' not in yaml_cfg]
if missing:
    raise ValueError(f'Behaviors missing from config: {missing}')

def is_configured(behavior, cfg):
    return behavior in cfg or 'default_settings' in cfg

from mlagents.trainers.exception import TrainerConfigError
try:
    trainer = TrainerController(...)
except TrainerConfigError as e:
    if 'has not been specified' in str(e):
        logger.error('Add config entry for behavior or default_settings: %s', e)

When it happens

Trigger: A behavior appears in the Unity environment (or was configured in a previous run) but its name is missing from the YAML trainer config, while no default_settings section exists.

Common situations: Renaming a behavior in Unity and not updating the config; multiple behaviors in a scene where only some are in the config; behavior names differing only in case or agent naming in Behavior Parameters.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Config file could not be found at {abs_path}.
• There was an error decoding Config file from {config_path}.
• Error parsing yaml file. Please check for formatting errors.
• Threshold for next lesson cannot be negative when the measur
• A non-terminal lesson does not have a completion_criteria fo

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