FoundationAgents/MetaGPT · error · ValueError

Unsupported react mode: {self.rc.react_mode}

Error message

Unsupported react mode: {self.rc.react_mode}

What it means

Role.react dispatches on rc.react_mode and supports only REACT, BY_ORDER, and PLAN_AND_ACT. Any other value (including react_mode=None or a string that failed enum coercion in some path) raises this ValueError. The mode comes from RoleReactMode configured via the role's options (react_mode key).

Source

Thrown at metagpt/roles/role.py:519

        Args:
            current_task (Task): current task to take on

        Raises:
            NotImplementedError: Specific Role must implement this method if expected to use planner

        Returns:
            TaskResult: Result from the actions
        """
        raise NotImplementedError

    async def react(self) -> Message:
        """Entry to one of three strategies by which Role reacts to the observed Message"""
        if self.rc.react_mode == RoleReactMode.REACT or self.rc.react_mode == RoleReactMode.BY_ORDER:
            rsp = await self._react()
        elif self.rc.react_mode == RoleReactMode.PLAN_AND_ACT:
            rsp = await self._plan_and_act()
        else:
            raise ValueError(f"Unsupported react mode: {self.rc.react_mode}")
        self._set_state(state=-1)  # current reaction is complete, reset state to -1 and todo back to None
        if isinstance(rsp, AIMessage):
            rsp.with_agent(self._setting)
        return rsp

    def get_memories(self, k=0) -> list[Message]:
        """A wrapper to return the most recent k memories of this role, return all when k=0"""
        return self.rc.memory.get(k=k)

    @role_raise_decorator
    async def run(self, with_message=None) -> Message | None:
        """Observe, and think and act based on the results of the observation"""
        if with_message:
            msg = None
            if isinstance(with_message, str):
                msg = Message(content=with_message)
            elif isinstance(with_message, Message):
                msg = with_message

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Use a valid RoleReactMode member: from metagpt.roles.role import RoleReactMode; role = MyRole(react_mode=RoleReactMode.BY_ORDER)
2. Check valid values via list(RoleReactMode) before assigning
3. If a string must cross a boundary, validate it against {e.value for e in RoleReactMode} first

Example fix

// before
role = MyRole(react_mode="byorder")  # ValueError in react()

// after
from metagpt.roles.role import RoleReactMode
role = MyRole(react_mode=RoleReactMode.BY_ORDER)

from metagpt.roles.role import RoleReactMode
assert role.rc.react_mode in (RoleReactMode.REACT, RoleReactMode.BY_ORDER, RoleReactMode.PLAN_AND_ACT)

from enum import Enum
from metagpt.roles.role import RoleReactMode

def is_valid_react_mode(mode) -> bool:
    return isinstance(mode, Enum) and mode in set(RoleReactMode)

try:
    rsp = await role.run()
except ValueError as e:
    if "Unsupported react mode" in str(e):
        role.rc.react_mode = RoleReactMode.REACT  # reset to safe default
        rsp = await role.run()
    else:
        raise

When it happens

Trigger: Creating a Role subclass with self.rc.react_mode set to an invalid value, e.g. RoleConfig/react_mode="plan-execute" or assigning an arbitrary string to rc.react_mode before calling role.run().

Common situations: Typo in react_mode in role kwargs (e.g. "by-order" vs "by_order"); copying a custom role that sets react_mode from unvalidated user input; version changes renaming enum members.

Related errors

• use `review` after `fill`
• please check MilvusConnection, uri must be set.
• please check QdrantConnection.
• not supported action_type: {action_type}
• Rollouts must be greater than 2 if there is no tree to load

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