Unity-Technologies/ml-agents · error · TrainerConfigError

Config doesn't specify a trainer type. Please specify traine

Error message

Config doesn't specify a trainer type. Please specify trainer: in your config.

What it means

upgrade_config.convert_behaviors() converts an old single-section YAML config into the newer per-behavior TrainerSettings/Hyperparameters/NetworkSettings format. It reads config["trainer"] to determine which hyperparameter class to use; a missing 'trainer' key means the legacy config doesn't say which trainer (ppo, sac, poca) it targets, so a TrainerConfigError is raised.

Source

Thrown at ml-agents/mlagents/trainers/upgrade_config.py:30

from mlagents.trainers.exception import TrainerConfigError
from mlagents.plugins import all_trainer_settings


# Take an existing trainer config (e.g. trainer_config.yaml) and turn it into the new format.
def convert_behaviors(old_trainer_config: Dict[str, Any]) -> Dict[str, Any]:
    all_behavior_config_dict = {}
    default_config = old_trainer_config.get("default", {})
    for behavior_name, config in old_trainer_config.items():
        if behavior_name != "default":
            config = default_config.copy()
            config.update(old_trainer_config[behavior_name])

            # Convert to split TrainerSettings, Hyperparameters, NetworkSettings
            # Set trainer_type and get appropriate hyperparameter settings
            try:
                trainer_type = config["trainer"]
            except KeyError:
                raise TrainerConfigError(
                    "Config doesn't specify a trainer type. "
                    "Please specify trainer: in your config."
                )
            new_config = {}
            new_config["trainer_type"] = trainer_type
            hyperparam_cls = all_trainer_settings[trainer_type]
            # Try to absorb as much as possible into the hyperparam_cls
            new_config["hyperparameters"] = cattr.structure(config, hyperparam_cls)

            # Try to absorb as much as possible into the network settings
            new_config["network_settings"] = cattr.structure(config, NetworkSettings)
            # Deal with recurrent
            try:
                if config["use_recurrent"]:
                    new_config[
                        "network_settings"
                    ].memory = NetworkSettings.MemorySettings(
                        sequence_length=config["sequence_length"],

View on GitHub (pinned to 3ecb446f75)

Solutions

Add a `trainer:` line to the config with the intended trainer type (ppo, sac, or poca).
If the config is a 3-component dict for a behavior, verify it is the full legacy dict including 'trainer', not a fragment.
Manually rewrite the config into the modern format (behaviors: <name>: with trainer_type, hyperparameters, network_settings) and skip the upgrade.
Check the original example configs shipped with your ML-Agents version and copy the trainer field from the matching trainer example.

Example fix

// before (legacy config.yaml)
batch_size: 1024
beta: 0.01
buffer_size: 10240
// after
trainer: ppo
batch_size: 1024
beta: 0.01
buffer_size: 10240

Defensive patterns

Strategy: validation

Validate before calling

import yaml

def validate_legacy_config(path):
    cfg = yaml.safe_load(open(path))
    if not isinstance(cfg, dict) or "trainer" not in cfg:
        raise ValueError(f"{path} must define a top-level 'trainer: ppo|sac|poca' before conversion")
    return cfg

Type guard

def has_trainer_type(cfg: dict) -> bool:
    return isinstance(cfg, dict) and isinstance(cfg.get("trainer"), str) and cfg["trainer"] in {"ppo", "sac", "poca"}

Try / catch

from mlagents.trainers.exception import TrainerConfigError
try:
    convert_behavior_configs(args)
except TrainerConfigError as e:
    if "specify a trainer type" in str(e):
        sys.exit(f"Config error: add 'trainer:' to your YAML. {e}")
    raise

Prevention

Always include trainer: in legacy configs before running --convert-to-config.
Validate YAML against ML-Agents' TrainerSettings schema before conversion.
Start from the official example configs for the target trainer type.
Prefer manually migrating to the modern behaviors: format to avoid the upgrader.

When it happens

Trigger: Running `mlagents-learn --convert-to-config` (which calls convert) on a legacy config YAML whose top-level dict has no 'trainer:' entry — e.g. hand-written or trimmed old configs that only list hyperparameters.

Common situations: Migrating very old ML-Agents configs (pre-0.13 style) that predate explicit trainer_type; copying a partial example config; deleting the trainer line while cleaning up.

Related errors

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