FoundationAgents/MetaGPT · error · RuntimeError

Failed to step Minecraft server

Error message

Failed to step Minecraft server

What it means

MinecraftExtEnv._step POSTs {code, programs} to the mineflayer bridge server's /step endpoint and raises RuntimeError('Failed to step Minecraft server') on any non-200 response. The wrapper unpauses the bot, sends the code, and pauses again; a failure means the Express bridge rejected or crashed executing the request rather than the game logic itself.

Source

Thrown at metagpt/environment/minecraft/minecraft_ext_env.py:174

        self.connected = True
        # All the reset in step will be soft
        self.reset_options["reset"] = "soft"
        self.pause()
        return json.loads(returned_data)

    @mark_as_writeable
    def _step(self, code: str, programs: str = "") -> dict:
        if not self.has_reset:
            raise RuntimeError("Environment has not been reset yet")
        self.check_process()
        self.unpause()
        data = {
            "code": code,
            "programs": programs,
        }
        res = requests.post(f"{self.server}/step", json=data, timeout=self.request_timeout)
        if res.status_code != 200:
            raise RuntimeError("Failed to step Minecraft server")
        returned_data = res.json()
        self.pause()
        return json.loads(returned_data)

    @mark_as_writeable
    def pause(self) -> bool:
        if self.mineflayer.is_running and not self.server_paused:
            res = requests.post(f"{self.server}/pause")
            if res.status_code == 200:
                self.server_paused = True
        return self.server_paused

    @mark_as_writeable
    def unpause(self) -> bool:
        if self.mineflayer.is_running and self.server_paused:
            res = requests.post(f"{self.server}/pause")
            if res.status_code == 200:
                self.server_paused = False

View on GitHub (pinned to 11cdf466d0)

Solutions

  1. Check that the Minecraft server is up and the mineflayer bridge (index.js) is running on the expected port before stepping.
  2. Validate/escape the code string — it is executed as JavaScript inside the bot; log it verbatim on failure to see what the bridge rejected.
  3. Call await env.reset() to re-establish the bot connection if the bot dropped, then retry the step.
  4. Look at the bridge process stdout/stderr — the HTTP response body usually carries the real exception but this wrapper discards it (res.text is not logged).

Example fix

# before
obs = await env.step("bot.chatt('hi')")  # typo -> bridge 500 -> RuntimeError

# after
code = "bot.chat('hi')"
try:
    obs = await env.step(code)
except RuntimeError as e:
    logger.error("step failed for code=%r", code)
    raise
Defensive patterns

Strategy: retry

Validate before calling

def bridge_ready(server: str, timeout=2) -> bool:
    import requests
    try:
        return requests.get(f"{server}/", timeout=timeout).status_code < 500
    except requests.RequestException:
        return False

assert bridge_ready(env.server), f"mineflayer bridge at {env.server} is not responding"

Try / catch

import asyncio

async def step_with_retry(env, code, attempts=3):
    for i in range(attempts):
        try:
            return await env.step(code)
        except RuntimeError as e:
            if "Failed to step" not in str(e) or i == attempts - 1:
                raise
            logger.warning("step failed (attempt %d), re-resetting bot", i + 1)
            await env.reset()
    raise RuntimeError("unreachable")

Prevention

When it happens

Trigger: await env.step(code) where the bridge returns 400/500: syntax errors in the injected JavaScript, bot not spawned (bridge started but never connected to Minecraft), server on a different port than mc_port, or the bridge process died and the connection is refused (requests raises before this check, but 5xx from a proxy lands here).

Common situations: Generated code strings that are not valid JavaScript; Minecraft server not running or bot disconnected mid-session; port mismatch between server config and the running bridge; bridge restarted externally while the env instance kept stale state.

Related errors

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