Unity-Technologies/ml-agents · error · UnitySideChannelException

You cannot set the width/height of the screen resolution wit

Error message

You cannot set the width/height of the screen resolution without also setting the height/width

What it means

set_configuration_parameters requires width and height to be set together when configuring screen resolution. Passing exactly one of them is ambiguous, so it raises UnitySideChannelException before sending any message.

Source

Thrown at ml-agents-envs/mlagents_envs/side_channel/engine_configuration_channel.py:86

        """
        Sets the engine configuration. Takes as input the configurations of the
        engine.
        :param width: Defines the width of the display. (Must be set alongside height)
        :param height: Defines the height of the display. (Must be set alongside width)
        :param quality_level: Defines the quality level of the simulation.
        :param time_scale: Defines the multiplier for the deltatime in the
        simulation. If set to a higher value, time will pass faster in the
        simulation but the physics might break.
        :param target_frame_rate: Instructs simulation to try to render at a
        specified frame rate.
        :param capture_frame_rate: Instructs the simulation to consider time between
        updates to always be constant, regardless of the actual frame rate.
        """

        if (width is None and height is not None) or (
            width is not None and height is None
        ):
            raise UnitySideChannelException(
                "You cannot set the width/height of the screen resolution without also setting the height/width"
            )

        if width is not None and height is not None:
            screen_msg = OutgoingMessage()
            screen_msg.write_int32(self.ConfigurationType.SCREEN_RESOLUTION)
            screen_msg.write_int32(width)
            screen_msg.write_int32(height)
            super().queue_message_to_send(screen_msg)

        if quality_level is not None:
            quality_level_msg = OutgoingMessage()
            quality_level_msg.write_int32(self.ConfigurationType.QUALITY_LEVEL)
            quality_level_msg.write_int32(quality_level)
            super().queue_message_to_send(quality_level_msg)

        if time_scale is not None:
            time_scale_msg = OutgoingMessage()

View on GitHub (pinned to 3ecb446f75)

Solutions

Pass both width and height (or neither): set_configuration_parameters(width=1280, height=720).
Default missing values explicitly, e.g. width=int(os.environ.get('WIDTH', 1280)).
Use the convenience set_configuration(...) which groups parameters, still supplying both dimensions.
Validate width/height are both None or both ints before calling.

Example fix

// before
engine_config_channel.set_configuration_parameters(width=1280)
// after
engine_config_channel.set_configuration_parameters(width=1280, height=720)

Defensive patterns

Strategy: validation

Validate before calling

def valid_resolution(width, height):
    return (width is None and height is None) or (isinstance(width, int) and isinstance(height, int) and width > 0 and height > 0)
assert valid_resolution(width, height), "width and height must both be set or both None"

Prevention

Always pass width and height together
Load both values from config with explicit defaults
Add a pre-call assertion or validation helper
Use set_configuration() to set grouped parameters consistently

When it happens

Trigger: Calling engine_config_channel.set_configuration_parameters(width=1280) or (height=720) without the other, then env.step().

Common situations: Scripted config where one resolution value comes from an env var/CLI arg that is missing; copy-paste edits dropping one parameter.

Related errors

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