Unity-Technologies/ml-agents · error · TrainerConfigError

Config doesn't specify use_recurrent. Please specify true or

Error message

Config doesn't specify use_recurrent. Please specify true or false for use_recurrent in your config.

What it means

upgrade_config.convert_behaviors() moves legacy use_recurrent/memory settings into a NetworkSettings.MemorySettings. When the legacy config contains sequence_length/memory_size handling, it also requires the 'use_recurrent' key to decide whether memory settings apply; its absence raises TrainerConfigError.

Source

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

            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"],
                        memory_size=config["memory_size"],
                    )
            except KeyError:
                raise TrainerConfigError(
                    "Config doesn't specify use_recurrent. "
                    "Please specify true or false for use_recurrent in your config."
                )
            # Absorb the rest into the base TrainerSettings
            for key, val in config.items():
                if key in attr.fields_dict(TrainerSettings):
                    new_config[key] = val

            # Structure the whole thing
            all_behavior_config_dict[behavior_name] = cattr.structure(
                new_config, TrainerSettings
            )
    return all_behavior_config_dict


def write_to_yaml_file(unstructed_config: Dict[str, Any], output_config: str) -> None:
    with open(output_config, "w") as f:
        try:

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Add `use_recurrent: true` (or `false`) to the legacy config before running the upgrade.
2. If you don't need memory (LSTM), remove sequence_length and memory_size keys as well and set use_recurrent: false.
3. Manually migrate the config to the modern format, placing sequence_length/memory under network_settings.memory (only if recurrent), avoiding the upgrader entirely.
4. Confirm the top-level dict passed to the upgrader isn't missing the key because it was nested under a behavior name.

Example fix

// before
use_vis_encoder_size: 64
sequence_length: 64
memory_size: 128
// after
use_recurrent: true
use_vis_encoder_size: 64
sequence_length: 64
memory_size: 128

import yaml

def validate_recurrent_fields(path):
    cfg = yaml.safe_load(open(path))
    memory_keys = {"sequence_length", "memory_size"}
    if memory_keys & set(cfg) and "use_recurrent" not in cfg:
        raise ValueError(f"{path} has memory settings but no 'use_recurrent: true|false'")

def has_use_recurrent(cfg: dict) -> bool:
    return isinstance(cfg, dict) and isinstance(cfg.get("use_recurrent"), bool)

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

When it happens

Trigger: Running the config upgrade (convert_behaviors via `mlagents-learn --convert-to-config`) on a legacy config that supplies memory fields (or reaches the memory block) but lacks a boolean 'use_recurrent:' entry at the top level.

Common situations: Upgrading old LSTM-era configs where use_recurrent was implicit or trimmed; hand-copying config fragments; removing 'use_recurrent: false' during cleanup while keeping sequence_length/memory_size keys.

Related errors

• Config doesn't specify a trainer type. Please specify traine
• There was an error decoding Config file from {config_path}.
• Error parsing yaml file. Please check for formatting errors.
• There was a problem reading a message in a SideChannel. Plea
• StatsSideChannel should never receive messages.

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