What causes "api_name: {api_name} not found" in FoundationAgents/MetaGPT?

List what is actually available: env.get_all_available_apis(mode='read') and mode='write' return the registered names and definitions.

FoundationAgents/MetaGPT · error · KeyError

api_name: {api_name} not found

Error message

api_name: {api_name} not found

What it means

EnvAPIRegistry.get raises KeyError('api_name: {name} not found') when the requested name is not in its registry dict. The registry is populated via __setitem__ / registration decorators by each ExtEnv implementation, so the error means the environment you are using never registered an API with that name (or you are querying the wrong registry — read vs write).

Source

Thrown at metagpt/environment/api/env_api.py:25

from pydantic import BaseModel, Field


class EnvAPIAbstract(BaseModel):
    """api/interface summary description"""

    api_name: str = Field(default="", description="the api function name or id")
    args: set = Field(default={}, description="the api function `args` params")
    kwargs: dict = Field(default=dict(), description="the api function `kwargs` params")


class EnvAPIRegistry(BaseModel):
    """the registry to store environment w&r api/interface"""

    registry: dict[str, Callable] = Field(default=dict(), exclude=True)

    def get(self, api_name: str):
        if api_name not in self.registry:
            raise KeyError(f"api_name: {api_name} not found")
        return self.registry.get(api_name)

    def __getitem__(self, api_name: str) -> Callable:
        return self.get(api_name)

    def __setitem__(self, api_name: str, func: Callable):
        self.registry[api_name] = func

    def __len__(self):
        return len(self.registry)

    def get_apis(self, as_str=True) -> dict[str, dict[str, Union[dict, Any, str]]]:
        """return func schema without func instance"""
        apis = dict()
        for func_name, func_schema in self.registry.items():
            new_func_schema = dict()
            for key, value in func_schema.items():
                if key == "func":

View on GitHub (pinned to 11cdf466d0)

Solutions

List what is actually available: env.get_all_available_apis(mode='read') and mode='write' return the registered names and definitions.
Match the mode: read APIs go through read_from_api, write APIs through write_to_api — using the wrong side raises this KeyError.
Check for typos and for the exact registered spelling (some names include prefixes/suffixes).
If the API genuinely should exist, upgrade/downgrade MetaGPT to the version whose environment registers it, or register it yourself via registry["name"] = func.

Example fix

# before
obs = await env.read_from_api("get_inventories")  # KeyError: api_name: get_inventories not found

# after
available = env.get_all_available_apis(mode="read")
assert "get_inventory" in available, f"known read apis: {list(available)}"
obs = await env.read_from_api("get_inventory")

Defensive patterns

Strategy: validation

Validate before calling

available = env.get_all_available_apis(mode="read")
if api_name not in available:
    raise KeyError(f"{api_name!r} not registered; available: {sorted(available)}")
obs = await env.read_from_api(api_name)

Type guard

def api_exists(env, api_name: str, mode: str = "read") -> bool:
    """True when the environment registered api_name for the given mode."""
    registry = env_read_api_registry if mode == "read" else env_write_api_registry
    return api_name in registry.registry

Try / catch

try:
    obs = await env.read_from_api(api_name)
except KeyError as e:
    known = sorted(env.get_all_available_apis(mode="read"))
    raise KeyError(f"unknown api {api_name!r}; registered read apis: {known}") from e

Prevention

Print get_all_available_apis() for both modes once per environment and drive calls from that list.
Keep api names as constants shared between registration and call sites instead of hand-typed strings.
Match read vs write registries — querying the wrong side is the most common miss.

When it happens

Trigger: env.read_from_api("some_api") or accessing env.api_registry["some_api"] where 'some_api' was never registered; calling a write API name against the read registry or vice versa; typo in the api_name string; using an ExtEnv subclass that does not implement that API.

Common situations: Copying example code from a different environment (e.g. a Minecraft API name used against the Android env); version changes that renamed or removed registered APIs; querying APIs before the environment instance registered them.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/920e7fa9aaa6a07e. Report an issue: GitHub.