Unity-Technologies/ml-agents · error · TrainerConfigError

Unsupported parameter randomization configuration {d}.

Error message

Unsupported parameter randomization configuration {d}.

What it means

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.

Source

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

    def __str__(self) -> str:
        """
        Helper method to output sampler stats to console.
        """
        raise TrainerConfigError(f"__str__ not implemented for type {self.__class__}.")

    @staticmethod
    def structure(
        d: Union[Mapping, float], t: type
    ) -> "ParameterRandomizationSettings":
        """
        Helper method to a ParameterRandomizationSettings class. Meant to be registered with
        cattr.register_structure_hook() and called with cattr.structure(). This is needed to handle
        the special Enum selection of ParameterRandomizationSettings classes.
        """
        if isinstance(d, (float, int)):
            return ConstantSettings(value=d)
        if not isinstance(d, Mapping):
            raise TrainerConfigError(
                f"Unsupported parameter randomization configuration {d}."
            )
        if "sampler_type" not in d:
            raise TrainerConfigError(
                f"Sampler configuration does not contain sampler_type : {d}."
            )
        if "sampler_parameters" not in d:
            raise TrainerConfigError(
                f"Sampler configuration does not contain sampler_parameters : {d}."
            )
        enum_key = ParameterRandomizationType(d["sampler_type"])
        t = enum_key.to_settings()
        return strict_to_cls(d["sampler_parameters"], t)

    @staticmethod
    def unstructure(d: "ParameterRandomizationSettings") -> Mapping:
        """
        Helper method to a ParameterRandomizationSettings class. Meant to be registered with

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Provide either a plain number for a constant parameter or a mapping with sampler_type and sampler_parameters keys.
2. Fix YAML indentation so the sampler block parses as a dict.
3. Check the config against the official ML-Agents randomization documentation schema.

Example fix

# before
environment_parameters:
  my_param:
    - uniform
    - 1.0
    - 5.0

# after
environment_parameters:
  my_param:
    sampler_type: uniform
    sampler_parameters:
      min_value: 1.0
      max_value: 5.0

for name, spec in cfg.get('environment_parameters', {}).items():
    if not (isinstance(spec, (int, float)) or isinstance(spec, dict)):
        raise ValueError(f'environment_parameters[{name}] must be a number or sampler mapping')

def is_param_spec(v) -> bool:
    return isinstance(v, (int, float)) or (isinstance(v, dict) and 'sampler_type' in v)

try:
    config = TrainerSettings.structure(raw)
except TrainerConfigError as e:
    if 'parameter randomization' in str(e):
        print('Fix environment_parameters block to number or {sampler_type, sampler_parameters}')
    raise

When it happens

Trigger: Providing `environment_parameters` randomization entries as a list, bare string, or null instead of a number or a `{sampler_type: ..., sampler_parameters: ...}` mapping.

Common situations: YAML typo where the sampler block got collapsed to a list, or copying config between ML-Agents versions with different randomization schema.

Related errors

• Unsupported reward signal configuration {d}.
• Sampler configuration does not contain sampler_type : {d}.
• Sampler configuration does not contain sampler_parameters :
• Minimum value is greater than maximum value in uniform sampl
• The sampling interval {interval} must contain exactly two va

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