Unity-Technologies/ml-agents · error · UnityTrainerException

Unknown StatsAggregationMethod encountered. {agg_type}

Error message

Unknown StatsAggregationMethod encountered. {agg_type}

What it means

AgentProcessor.record_environment_stats reads a StatsSummary's aggregation type and only handles SUM/AVERAGE/HISTOGRAM/MOST_RECENT. An unknown StatsAggregationMethod means a new enum value from a different mlagents version or an uninitialized/invalid StatsSummary, so UnityTrainerException is raised.

Source

Thrown at ml-agents/mlagents/trainers/agent_processor.py:467

        :param env_stats:
        :param worker_id:
        :return:
        """
        for stat_name, value_list in env_stats.items():
            for val, agg_type in value_list:
                if agg_type == StatsAggregationMethod.AVERAGE:
                    self._stats_reporter.add_stat(stat_name, val, agg_type)
                elif agg_type == StatsAggregationMethod.SUM:
                    self._stats_reporter.add_stat(stat_name, val, agg_type)
                elif agg_type == StatsAggregationMethod.HISTOGRAM:
                    self._stats_reporter.add_stat(stat_name, val, agg_type)
                elif agg_type == StatsAggregationMethod.MOST_RECENT:
                    # In order to prevent conflicts between multiple environments,
                    # only stats from the first environment are recorded.
                    if worker_id == 0:
                        self._stats_reporter.set_stat(stat_name, val)
                else:
                    raise UnityTrainerException(
                        f"Unknown StatsAggregationMethod encountered. {agg_type}"
                    )

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Match mlagents_envs and mlagents package versions (pip install -U mlagents==<envs version pair>).
2. Only pass StatsSummary objects created by the standard env-stats path, not hand-built ones.
3. Update the package so both sides share the same StatsAggregationMethod enum.
4. Catch UnityTrainerException and log the offending agg_type value for diagnosis.

Example fix

// before
summary = StatsSummary(value_list=[1.0], agg_type=MyCustomAggType)  # unsupported
trainer.record_environment_stats(summary, worker_id=0)
// after
from mlagents_envs.side_channel.stats_side_channel import StatsAggregationMethod
summary = StatsSummary(value_list=[1.0], agg_type=StatsAggregationMethod.AVERAGE)
trainer.record_environment_stats(summary, worker_id=0)

from mlagents_envs.side_channel.stats_side_channel import StatsAggregationMethod
assert stats_summary.agg_type in {StatsAggregationMethod.SUM, StatsAggregationMethod.AVERAGE, StatsAggregationMethod.HISTOGRAM, StatsAggregationMethod.MOST_RECENT}

def is_supported_agg(agg_type) -> bool:
    return agg_type in {StatsAggregationMethod.SUM, StatsAggregationMethod.AVERAGE,
                        StatsAggregationMethod.HISTOGRAM, StatsAggregationMethod.MOST_RECENT}

from mlagents.trainers.exception import UnityTrainerException
try:
    agent_processor.record_environment_stats(stats_summary, worker_id)
except UnityTrainerException as e:
    logging.error("Unsupported stats aggregation (version mismatch?): %s", e)

When it happens

Trigger: Calling record_environment_stats with a StatsSummary whose agg_type is not one of the four supported StatsAggregationMethod values (e.g. enum added in a newer package, or a manually constructed StatsSummary with a bad value).

Common situations: Mixing mlagents/mlagents_envs versions so env stats carry an aggregation type the trainer does not know; custom training loops constructing StatsSummary incorrectly.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• API versions of demonstration are incompatible.
• Variable Length Observations are not supported by the traine
• There was a problem reading a message in a SideChannel. Plea
• StatsSideChannel should never receive messages.
• The communication API version is not compatible between Unit

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