Implementation:Farama Foundation Gymnasium Error Hierarchy

Knowledge Sources	Farama_Foundation_Gymnasium Gymnasium Docs
Domains	Reinforcement_Learning, Error_Handling
Last Updated	2026-02-15 03:00 GMT

Overview

Defines the complete exception class hierarchy used throughout the Gymnasium library for registration errors, environment errors, wrapper errors, and vectorized environment errors.

Description

The error module provides a structured hierarchy of exception classes organized into four categories:

Registration Errors (inherit from Error):

• Error -- The base superclass for all Gymnasium errors.
• UnregisteredEnv -- Raised when requesting an environment not in the registry.
• NamespaceNotFound -- Raised when the namespace portion of an env ID does not exist.
• NameNotFound -- Raised when the name portion of an env ID does not exist.
• VersionNotFound -- Raised when the version portion of an env ID does not exist.
• DeprecatedEnv -- Raised when requesting an older version when a newer one exists.
• RegistrationError -- Raised for invalid registration attempts (e.g., unversioned env when versioned exists).

Environment Errors (inherit from Error):

• DependencyNotInstalled -- Raised when a required dependency (e.g., pygame, mujoco) is missing.
• UnsupportedMode -- Raised for unsupported render modes.
• InvalidMetadata -- Raised for invalid environment metadata.
• ResetNeeded -- Raised when step or render is called before reset.
• InvalidAction -- Raised for out-of-space actions.
• MissingArgument -- Raised when a required constructor argument is missing.
• InvalidProbability -- Raised for invalid probability values.
• InvalidBound -- Raised for invalid clipping bounds.

Wrapper Errors:

• DeprecatedWrapper (inherits from ImportError) -- Raised when importing an old wrapper version.

Vectorized Environment Errors (inherit from Exception):

• AlreadyPendingCallError -- Raised for duplicate async calls without awaiting the previous one.
• NoAsyncCallError -- Raised when awaiting an async call that was never started.
• ClosedEnvironmentError -- Raised when operating on a closed environment.
• CustomSpaceError -- Raised when a custom space is incompatible with shared memory in AsyncVectorEnv.

Usage

Use these exception classes when implementing custom environments, wrappers, or registration logic to raise semantically meaningful errors that align with the Gymnasium error hierarchy. Catch these exceptions when building robust environment management code.

Code Reference

Source Location

• Repository: Farama_Foundation_Gymnasium
• File: gymnasium/error.py

Signature

class Error(Exception): ...
class UnregisteredEnv(Error): ...
class NamespaceNotFound(UnregisteredEnv): ...
class NameNotFound(UnregisteredEnv): ...
class VersionNotFound(UnregisteredEnv): ...
class DeprecatedEnv(Error): ...
class RegistrationError(Error): ...
class DependencyNotInstalled(Error): ...
class ResetNeeded(Error): ...
class InvalidAction(Error): ...
class AlreadyPendingCallError(Exception): ...
class NoAsyncCallError(Exception): ...
class ClosedEnvironmentError(Exception): ...
class CustomSpaceError(Exception): ...

Import

from gymnasium.error import (
    Error,
    UnregisteredEnv,
    DependencyNotInstalled,
    ResetNeeded,
    InvalidAction,
    ClosedEnvironmentError,
)

I/O Contract

Inputs

Name	Type	Required	Description
message	str	Yes	Error message describing the issue
name	str	Yes (for AlreadyPendingCallError, NoAsyncCallError)	Name of the pending call (e.g., "step", "reset")

Outputs

Name	Type	Description
exception	Exception	Raised exception instance with the provided message

Usage Examples

from gymnasium.error import DependencyNotInstalled, ResetNeeded

# In environment implementation
try:
    import pygame
except ImportError as e:
    raise DependencyNotInstalled(
        'pygame is not installed, run `pip install "gymnasium[classic_control]"`'
    ) from e

# In wrapper enforcement
class OrderEnforcing:
    def step(self, action):
        if not self._has_reset:
            raise ResetNeeded("Cannot call step() before reset()")
        return self.env.step(action)

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime