Unity-Technologies/ml-agents · error · TrainerConfigError

Hyperparameters were specified but no trainer_type was given

Error message

Hyperparameters were specified but no trainer_type was given.

What it means

When the 'hyperparameters' key is present in a trainer config, the trainer_type must also be specified, since hyperparameter classes differ per trainer (PPO/SAC/POCA). mlagents raises TrainerConfigError when hyperparameters are given without trainer_type.

Source

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

        # Check if a default_settings was specified. If so, used those as the default
        # rather than an empty dict.
        if TrainerSettings.default_override is not None:
            d_copy.update(cattr.unstructure(TrainerSettings.default_override))

        deep_update_dict(d_copy, d)

        if "framework" in d_copy:
            logger.warning("Framework option was deprecated but was specified")
            d_copy.pop("framework", None)

        for key, val in d_copy.items():
            if attr.has(type(val)):
                # Don't convert already-converted attrs classes.
                continue
            if key == "hyperparameters":
                if "trainer_type" not in d_copy:
                    raise TrainerConfigError(
                        "Hyperparameters were specified but no trainer_type was given."
                    )
                else:
                    d_copy[key] = check_hyperparam_schedules(
                        val, d_copy["trainer_type"]
                    )
                    try:
                        d_copy[key] = strict_to_cls(
                            d_copy[key], all_trainer_settings[d_copy["trainer_type"]]
                        )
                    except KeyError:
                        raise TrainerConfigError(
                            f"Settings for trainer type {d_copy['trainer_type']} were not found"
                        )
            elif key == "max_steps":
                d_copy[key] = int(float(val))
                # In some legacy configs, max steps was specified as a float
            # elif key == "even_checkpoints":

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Add trainer_type: ppo|sac|poca at the same level as hyperparameters.
2. Remove hyperparameters from default_settings if they shouldn't apply universally, or add trainer_type to default_settings.
3. Verify per-behavior configs for behaviors inheriting default hyperparameters.

Example fix

// before
MyBehavior:
  hyperparameters:
    batch_size: 64
// after
MyBehavior:
  trainer_type: ppo
  hyperparameters:
    batch_size: 64

if 'hyperparameters' in cfg and 'trainer_type' not in cfg:
    raise ValueError('hyperparameters given without trainer_type')

def has_trainer_type(cfg):
    return isinstance(cfg, dict) and isinstance(cfg.get('trainer_type'), str) and cfg['trainer_type']

from mlagents.trainers.exception import TrainerConfigError
try:
    load_config(path)
except TrainerConfigError as e:
    if 'no trainer_type' in str(e):
        cfg.setdefault('trainer_type', 'ppo')
    else:
        raise

When it happens

Trigger: A behavior config includes hyperparameters but omits trainer_type, or default_settings provides hyperparameters while the behavior-level dict lacks trainer_type.

Common situations: Trimming configs and accidentally deleting trainer_type; relying on default_settings that include hyperparameters for a behavior that has no trainer_type; migrating legacy configs.

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/a4d663809ca8e0d2. Report an issue: GitHub.