Unity-Technologies/ml-agents · error · TrainerConfigError

Unsupported parameter environment parameter settings {d}.

Error message

Unsupported parameter environment parameter settings {d}.

What it means

The cattr structuring hook for environment parameters requires the input to be a Mapping (dict). If the raw value for environment parameters is any other type, mlagents wraps it in TrainerConfigError indicating the settings are unsupported.

Source

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

                raise TrainerConfigError(
                    f"A non-terminal lesson does not have a completion_criteria for {parameter_name}."
                )
            if index == num_lessons - 1 and lesson.completion_criteria is not None:
                warnings.warn(
                    f"Your final lesson definition contains completion_criteria for {parameter_name}."
                    f"It will be ignored.",
                    TrainerConfigWarning,
                )

    @staticmethod
    def structure(d: Mapping, t: type) -> Dict[str, "EnvironmentParameterSettings"]:
        """
        Helper method to structure a Dict of EnvironmentParameterSettings class. Meant
        to be registered with cattr.register_structure_hook() and called with
        cattr.structure().
        """
        if not isinstance(d, Mapping):
            raise TrainerConfigError(
                f"Unsupported parameter environment parameter settings {d}."
            )
        d_final: Dict[str, EnvironmentParameterSettings] = {}
        for environment_parameter, environment_parameter_config in d.items():
            if (
                isinstance(environment_parameter_config, Mapping)
                and "curriculum" in environment_parameter_config
            ):
                d_final[environment_parameter] = strict_to_cls(
                    environment_parameter_config, EnvironmentParameterSettings
                )
                EnvironmentParameterSettings._check_lesson_chain(
                    d_final[environment_parameter].curriculum, environment_parameter
                )
            else:
                sampler = ParameterRandomizationSettings.structure(
                    environment_parameter_config, ParameterRandomizationSettings
                )

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Ensure the environment_parameters value is a mapping: {param_name: {curriculum: ...} or a scalar}.
2. Check YAML indentation so the block nests correctly under environment_parameters.
3. Log/print the parsed dict before structuring to confirm its type.

Example fix

# before
environment_parameters:
  - goal_size
# after
environment_parameters:
  goal_size:
    curriculum:
      - value: 1.0

if not isinstance(cfg.get('environment_parameters'), dict):
    raise ValueError('environment_parameters must be a mapping of parameter name -> settings')

def is_param_settings(x):
    return isinstance(x, dict) and all(isinstance(k, str) for k in x.keys())

from mlagents.trainers.exception import TrainerConfigError
try:
    structure_env_params(d)
except TrainerConfigError as e:
    logger.error('Bad environment_parameters section: %s', e)

When it happens

Trigger: Passing a non-dict (list, string, None) where the 'environment_parameters' section expects a dict of {parameter_name: config}, e.g. via YAML that parsed a scalar, or calling cattr.structure manually with a non-Mapping object.

Common situations: YAML configs where indentation makes the parameter block a string or list; programmatically building EnvironmentParameterSettings from JSON that isn't a dict; typos turning the section into a scalar.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unable to convert {encoded_key} to an AgentBufferKey
• Config file could not be found at {abs_path}.
• There was an error decoding Config file from {config_path}.
• Error parsing yaml file. Please check for formatting errors.
• Threshold for next lesson cannot be negative when the measur

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