Unity-Technologies/ml-agents · error · KeyError

The entry {identifier} is not present in the registry.

Error message

The entry {identifier} is not present in the registry.

What it means

KeyError raised by UnityEnvRegistry.__getitem__ when the requested identifier was not found among registered environment entries (after loading all available manifests). It is the registry's way of reporting an unknown environment name.

Source

Thrown at ml-agents-envs/mlagents_envs/registry/unity_env_registry.py:110

    def clear(self) -> None:
        """
        Deletes all entries in the registry.
        """
        self._REGISTERED_ENVS.clear()
        self._manifests = []
        self._sync = True

    def __getitem__(self, identifier: str) -> BaseRegistryEntry:
        """
        Returns the BaseRegistryEntry with the provided identifier. BaseRegistryEntry
        can then be used to make a Unity Environment.
        :param identifier: The identifier of the BaseRegistryEntry
        :returns: The associated BaseRegistryEntry
        """
        self._load_all_manifests()
        if identifier not in self._REGISTERED_ENVS:
            raise KeyError(f"The entry {identifier} is not present in the registry.")
        return self._REGISTERED_ENVS[identifier]

    def __len__(self) -> int:
        self._load_all_manifests()
        return len(self._REGISTERED_ENVS)

    def __iter__(self) -> Iterator[Any]:
        self._load_all_manifests()
        yield from self._REGISTERED_ENVS


default_registry = UnityEnvRegistry()
# TODO restore when a new registry is available.
default_registry.register_from_yaml(
    "https://storage.googleapis.com/mlagents-test-environments/1.1.0/manifest.yaml"
)  # noqa E501

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Print list(registry) (or iterate __len__/keys via the registry) to see available identifiers and correct the name.
2. Register the entry first: registry.register(name, ... or manifest_path) before lookup.
3. Wrap lookup with `if identifier in registry` (uses __contains__/len semantics) or try/except KeyError.
4. Ensure the manifest JSON with the entry is discoverable (correct path/URL passed to UnityEnvRegistry).

Example fix

// before
entry = registry['3DBall']  # KeyError: registered as '3dball'
// after
entry = registry['3dball']  # or: check `if '3DBall' in registry` first

identifier = '3dball'
if identifier not in registry:  # triggers manifest load
    raise KeyError(f"{identifier} not registered; available: {[e for e in registry]}")
entry = registry[identifier]

def get_entry(registry, identifier: str):
    return registry[identifier] if identifier in registry else None

try:
    entry = registry[identifier]
except KeyError as e:
    logger.error("Unknown env id %s; available=%s", identifier, list(registry))
    raise

When it happens

Trigger: registry['name'] where 'name' was never registered via register() or listed in any loaded manifest JSON.

Common situations: Typo in the environment identifier; forgetting to register a custom entry before lookup; manifest file not on the path / not loaded; casing mismatch in the id.

Related errors

• agent_id {agent_id} is not present in the DecisionSteps
• agent_id {agent_id} is not present in the TerminalSteps
• The make() method not implemented for entry {self.identifier
• There was a problem reading a message in a SideChannel. Plea
• StatsSideChannel should never receive messages.

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