{"record":{"id":"d616f59c0b82cf71","repo":"Unity-Technologies/ml-agents","slug":"unsupported-parameter-randomization-configuration","errorCode":null,"errorMessage":"Unsupported parameter randomization configuration {d}.","messagePattern":"Unsupported parameter randomization configuration (.+?)\\.","errorType":"validation","errorClass":"TrainerConfigError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/settings.py","lineNumber":293,"sourceCode":"    def __str__(self) -> str:\n        \"\"\"\n        Helper method to output sampler stats to console.\n        \"\"\"\n        raise TrainerConfigError(f\"__str__ not implemented for type {self.__class__}.\")\n\n    @staticmethod\n    def structure(\n        d: Union[Mapping, float], t: type\n    ) -> \"ParameterRandomizationSettings\":\n        \"\"\"\n        Helper method to a ParameterRandomizationSettings class. Meant to be registered with\n        cattr.register_structure_hook() and called with cattr.structure(). This is needed to handle\n        the special Enum selection of ParameterRandomizationSettings classes.\n        \"\"\"\n        if isinstance(d, (float, int)):\n            return ConstantSettings(value=d)\n        if not isinstance(d, Mapping):\n            raise TrainerConfigError(\n                f\"Unsupported parameter randomization configuration {d}.\"\n            )\n        if \"sampler_type\" not in d:\n            raise TrainerConfigError(\n                f\"Sampler configuration does not contain sampler_type : {d}.\"\n            )\n        if \"sampler_parameters\" not in d:\n            raise TrainerConfigError(\n                f\"Sampler configuration does not contain sampler_parameters : {d}.\"\n            )\n        enum_key = ParameterRandomizationType(d[\"sampler_type\"])\n        t = enum_key.to_settings()\n        return strict_to_cls(d[\"sampler_parameters\"], t)\n\n    @staticmethod\n    def unstructure(d: \"ParameterRandomizationSettings\") -> Mapping:\n        \"\"\"\n        Helper method to a ParameterRandomizationSettings class. Meant to be registered with","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/settings.py#L275-L311","documentation":"The structure hook for ParameterRandomizationSettings accepts either a scalar (treated as ConstantSettings) or a Mapping describing a sampler; anything else (list, string, None) is rejected with this error. It guards the Enum-based selection of the correct sampler settings class.","triggerScenarios":"Providing `environment_parameters` randomization entries as a list, bare string, or null instead of a number or a `{sampler_type: ..., sampler_parameters: ...}` mapping.","commonSituations":"YAML typo where the sampler block got collapsed to a list, or copying config between ML-Agents versions with different randomization schema.","solutions":["Provide either a plain number for a constant parameter or a mapping with sampler_type and sampler_parameters keys.","Fix YAML indentation so the sampler block parses as a dict.","Check the config against the official ML-Agents randomization documentation schema."],"exampleFix":"# before\nenvironment_parameters:\n  my_param:\n    - uniform\n    - 1.0\n    - 5.0\n\n# after\nenvironment_parameters:\n  my_param:\n    sampler_type: uniform\n    sampler_parameters:\n      min_value: 1.0\n      max_value: 5.0","handlingStrategy":"validation","validationCode":"for name, spec in cfg.get('environment_parameters', {}).items():\n    if not (isinstance(spec, (int, float)) or isinstance(spec, dict)):\n        raise ValueError(f'environment_parameters[{name}] must be a number or sampler mapping')","typeGuard":"def is_param_spec(v) -> bool:\n    return isinstance(v, (int, float)) or (isinstance(v, dict) and 'sampler_type' in v)","tryCatchPattern":"try:\n    config = TrainerSettings.structure(raw)\nexcept TrainerConfigError as e:\n    if 'parameter randomization' in str(e):\n        print('Fix environment_parameters block to number or {sampler_type, sampler_parameters}')\n    raise","preventionTips":["Model every randomization entry as either a scalar or a full sampler dict","Validate with a JSON/YAML schema matching ML-Agents' sampler types","Test config loading in CI before launching training"],"tags":["config","yaml","parameter-randomization","validation"],"backgroundTag":"invalid-config-schema","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}