{"record":{"id":"c9de40c4f5148b29","repo":"Unity-Technologies/ml-agents","slug":"the-option-key-was-specified-in-your-yaml-file-f","errorCode":null,"errorMessage":"The option {key} was specified in your YAML file for {class_type.__name__}, but is invalid.","messagePattern":"The option (.+?) was specified in your YAML file for (.+?), but is invalid\\.","errorType":"validation","errorClass":"TrainerConfigError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/settings.py","lineNumber":41,"sourceCode":"import copy\n\nfrom mlagents.trainers.cli_utils import StoreConfigFile, DetectDefault, parser\nfrom mlagents.trainers.cli_utils import load_config\nfrom mlagents.trainers.exception import TrainerConfigError, TrainerConfigWarning\n\nfrom mlagents_envs import logging_util\nfrom mlagents_envs.side_channel.environment_parameters_channel import (\n    EnvironmentParametersChannel,\n)\nfrom mlagents.plugins import all_trainer_settings, all_trainer_types\n\nlogger = logging_util.get_logger(__name__)\n\n\ndef check_and_structure(key: str, value: Any, class_type: type) -> Any:\n    attr_fields_dict = attr.fields_dict(class_type)\n    if key not in attr_fields_dict:\n        raise TrainerConfigError(\n            f\"The option {key} was specified in your YAML file for {class_type.__name__}, but is invalid.\"\n        )\n    # Apply cattr structure to the values\n    return cattr.structure(value, attr_fields_dict[key].type)\n\n\ndef check_hyperparam_schedules(val: Dict, trainer_type: str) -> Dict:\n    # Check if beta and epsilon are set. If not, set to match learning rate schedule.\n    if trainer_type == \"ppo\" or trainer_type == \"poca\":\n        if \"beta_schedule\" not in val.keys() and \"learning_rate_schedule\" in val.keys():\n            val[\"beta_schedule\"] = val[\"learning_rate_schedule\"]\n        if (\n            \"epsilon_schedule\" not in val.keys()\n            and \"learning_rate_schedule\" in val.keys()\n        ):\n            val[\"epsilon_schedule\"] = val[\"learning_rate_schedule\"]\n    return val\n","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/settings.py#L23-L59","documentation":"TrainerConfigError raised by check_and_structure when a key in the trainer YAML config is not a recognized attrs field on the target settings class. ML-Agents strictly validates config keys against the attrs classes (TrainerSettings, PPOSettings, etc.) and rejects unknown options rather than silently ignoring them. Called for each key during structure()/strict_to_cls() config loading.","triggerScenarios":"Any YAML key that doesn't match an attrs field name of the settings class — misspelled options (e.g. 'lamda' vs 'lambd'), options placed in the wrong section (e.g. beta under SAC hyperparameters), or options removed/renamed in a newer ML-Agents version.","commonSituations":"Old configs from ML-Agents 0.x used with the PyTorch release (renamed options like use_recurrent -> memory, summary_freq placement); typos like 'batchsize'; copying examples from outdated tutorials.","solutions":["Check the spelling of the flagged key against the settings class in mlagents/trainers/settings.py (e.g. lambd, not lambda or lamda).","Move the option to the correct nesting level — many options belong under hyperparameters or network_settings, not the top level.","If upgrading from an older version, migrate removed/renamed options per the ML-Agents migration guide.","Run the config through the config validator (mlagents-learn will print which key/class failed) and delete or correct invalid keys."],"exampleFix":"# before (SAC hyperparameters)\nhyperparameters:\n  learning_rate_schedule: constant\n  buffer_size: 50000\n  beta: 0.005   # PPO-only option\n# after\nhyperparameters:\n  learning_rate_schedule: constant\n  buffer_size: 50000","handlingStrategy":"validation","validationCode":"import yaml, attr\nfrom mlagents.trainers.settings import TrainerSettings\nraw = yaml.safe_load(open(\"config.yaml\"))\nvalid = set(attr.fields_dict(TrainerSettings)) | set(attr.fields_dict(type(raw.get(\"hyperparameters\", object))))\nunknown = set(raw) - valid\nif unknown:\n    print(f\"Unknown top-level options: {unknown}\")","typeGuard":"import attr\ndef keys_are_valid(d: dict, cls: type) -> bool:\n    fields = set(attr.fields_dict(cls))\n    return set(d) <= fields","tryCatchPattern":"from mlagents.trainers.exception import TrainerConfigError\ntry:\n    settings = load_config(\"config.yaml\")\nexcept TrainerConfigError as e:\n    logger.error(f\"Fix config: {e}\")\n    raise SystemExit(1)","preventionTips":["Compare keys against the attrs classes in mlagents/trainers/settings.py","When upgrading ML-Agents versions, re-check every option against the current migration guide","Start from the official sample configs (ml-agents/config/) rather than hand-writing YAML","Run a short 1000-step training to validate config before long runs"],"tags":["ml-agents","configuration","yaml","schema-validation","typo"],"backgroundTag":"invalid-config-option","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}