Unity-Technologies/ml-agents · error · UnityEnvironmentException

No Unity environment is loaded.

Error message

No Unity environment is loaded.

What it means

UnityEnvironmentException raised by UnityEnvironment.reset when self._loaded is False, i.e. reset() was called before a Unity environment was successfully loaded (or after it was closed/not yet initialized). The environment has no loaded instance to reset, so the library refuses the call.

Source

Thrown at ml-agents-envs/mlagents_envs/environment.py:329

                    DecisionSteps.empty(self._env_specs[brain_name]),
                    TerminalSteps.empty(self._env_specs[brain_name]),
                )
        self._side_channel_manager.process_side_channel_message(output.side_channel)

    def reset(self) -> None:
        if self._loaded:
            outputs = self._communicator.exchange(
                self._generate_reset_input(), self._poll_process
            )
            if outputs is None:
                raise UnityCommunicatorStoppedException("Communicator has exited.")
            self._update_behavior_specs(outputs)
            rl_output = outputs.rl_output
            self._update_state(rl_output)
            self._is_first_message = False
            self._env_actions.clear()
        else:
            raise UnityEnvironmentException("No Unity environment is loaded.")

    @timed
    def step(self) -> None:
        if self._is_first_message:
            return self.reset()
        if not self._loaded:
            raise UnityEnvironmentException("No Unity environment is loaded.")
        # fill the blanks for missing actions
        for group_name in self._env_specs:
            if group_name not in self._env_actions:
                n_agents = 0
                if group_name in self._env_state:
                    n_agents = len(self._env_state[group_name][0])
                self._env_actions[group_name] = self._env_specs[
                    group_name
                ].action_spec.empty_action(n_agents)
        step_input = self._generate_step_input(self._env_actions)
        with hierarchical_timer("communicator.exchange"):

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Ensure the UnityEnvironment was constructed successfully with a valid file_name (or a running Editor) before calling reset.
2. Do not call reset after env.close(); create a new UnityEnvironment instance instead.
3. Check the environment state before resetting: only reset when env is loaded.

Example fix

// before
env = UnityEnvironment('env.x86_64')
env.close()
env.reset()  # UnityEnvironmentException: No Unity environment is loaded

// after
env = UnityEnvironment('env.x86_64')
env.reset()
env.close()
env = UnityEnvironment('env.x86_64')
env.reset()

if not getattr(env, '_loaded', False):
    raise RuntimeError('Cannot reset: no Unity environment is loaded')
env.reset()

from mlagents_envs.exception import UnityEnvironmentException
try:
    env.reset()
except UnityEnvironmentException as e:
    if 'No Unity environment is loaded' in str(e):
        print('Construct a valid UnityEnvironment before calling reset().')
    raise

When it happens

Trigger: Calling env.reset() on a UnityEnvironment constructed but never loaded, or after _close(); or on an instance where initialization failed to set _loaded=True.

Common situations: Calling reset in a finally/cleanup block after close(); catching an earlier constructor failure and still attempting reset; using an environment object after its context manager exited.

Related errors

• num_envs must be 1 if env_path is not set.

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