{"record":{"id":"f3d3ddb13b56000d","repo":"Unity-Technologies/ml-agents","slug":"the-behavior-name-key-has-not-been-specified-in","errorCode":null,"errorMessage":"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.","messagePattern":"The behavior name (.+?) has not been specified in the trainer configuration\\. Please add an entry in the configuration file for (.+?), or set default_settings\\.","errorType":"validation","errorClass":"TrainerConfigError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/settings.py","lineNumber":745,"sourceCode":"    class DefaultTrainerDict(collections.defaultdict):\n        def __init__(self, *args):\n            # Depending on how this is called, args may have the defaultdict\n            # callable at the start of the list or not. In particular, unpickling\n            # will pass [TrainerSettings].\n            if args and args[0] == TrainerSettings:\n                super().__init__(*args)\n            else:\n                super().__init__(TrainerSettings, *args)\n            self._config_specified = True\n\n        def set_config_specified(self, require_config_specified: bool) -> None:\n            self._config_specified = require_config_specified\n\n        def __missing__(self, key: Any) -> \"TrainerSettings\":\n            if TrainerSettings.default_override is not None:\n                self[key] = copy.deepcopy(TrainerSettings.default_override)\n            elif self._config_specified:\n                raise TrainerConfigError(\n                    f\"The behavior name {key} has not been specified in the trainer configuration. \"\n                    f\"Please add an entry in the configuration file for {key}, or set default_settings.\"\n                )\n            else:\n                logger.warning(\n                    f\"Behavior name {key} does not match any behaviors specified \"\n                    f\"in the trainer configuration file. A default configuration will be used.\"\n                )\n                self[key] = TrainerSettings()\n            return self[key]\n\n\n# COMMAND LINE #########################################################################\n@attr.s(auto_attribs=True)\nclass CheckpointSettings:\n    run_id: str = parser.get_default(\"run_id\")\n    initialize_from: Optional[str] = parser.get_default(\"initialize_from\")\n    load_model: bool = parser.get_default(\"load_model\")","sourceCodeStart":727,"sourceCodeEnd":763,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/settings.py#L727-L763","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a top-level entry for the missing behavior name in the trainer config YAML.","Add a default_settings section so unlisted behaviors inherit defaults.","Match the behavior name exactly to the Behavior Name field in the Unity agent's Behavior Parameters."],"exampleFix":"# before\nBehaviorA:\n  trainer_type: ppo\n  ...\n# after\ndefault_settings:\n  trainer_type: ppo\nBehaviorA:\n  trainer_type: ppo\n  ...\nBehaviorB:\n  trainer_type: ppo","handlingStrategy":"try-catch","validationCode":"behaviors = collect_behavior_names_from_env()\nmissing = [b for b in behaviors if b not in yaml_cfg and 'default_settings' not in yaml_cfg]\nif missing:\n    raise ValueError(f'Behaviors missing from config: {missing}')","typeGuard":"def is_configured(behavior, cfg):\n    return behavior in cfg or 'default_settings' in cfg","tryCatchPattern":"from mlagents.trainers.exception import TrainerConfigError\ntry:\n    trainer = TrainerController(...)\nexcept TrainerConfigError as e:\n    if 'has not been specified' in str(e):\n        logger.error('Add config entry for behavior or default_settings: %s', e)","preventionTips":["Keep behavior names in Unity identical to config keys","Add a default_settings section as a safety net for unlisted behaviors","Re-check configs after renaming behaviors in Unity"],"tags":["config","ml-agents"],"backgroundTag":"missing-required-config-field","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}