agentscope-ai/agentscope · error · ValueError

Tool groups must not contain duplicate tool groups.

Error message

Tool groups must not contain duplicate tool groups.

What it means

Raised by Toolkit.__init__ when two or more tool groups passed to the toolkit share the same name. The toolkit relies on group names being unique to route tool registration and activation, so duplicates are rejected eagerly at construction time.

Source

Thrown at src/agentscope/tool/_toolkit.py:140

                "group. Don't include 'basic' in the tool_groups argument "
                "when you also provide tools, skills or mcps in the "
                "constructor.",
            )

        self.tool_groups = [
            ToolGroup(
                name="basic",
                tools=tools or [],
                skills_or_loaders=skills_or_loaders or [],
                mcps=mcps or [],
            ),
        ] + (tool_groups or [])

        # Check name conflict for tool groups
        if len(set(_.name for _ in self.tool_groups)) != len(
            self.tool_groups,
        ):
            raise ValueError(
                "Tool groups must not contain duplicate tool groups.",
            )

        # The stateful MCP clients should be initialized already
        for group in self.tool_groups:
            for client in group.mcps:
                if client.is_stateful and not client.is_connected:
                    raise ValueError(
                        f"The MCP client '{client.name}' is stateful, but "
                        f"not connected.",
                    )

        self.meta_tool_response_template = meta_tool_response_template
        self.skill_instruction_template = skill_instruction_template

        self.builtin_meta_tool = RegisteredTool(
            tool=ResetTools(
                # An inference value for groups so that it can generate the

View on GitHub (pinned to e90f1c7592)

Solutions

1. Check the names of every ToolGroup you pass: [g.name for g in tool_groups] and remove/rename the duplicate
2. If building the list dynamically, de-duplicate by name before constructing the Toolkit: seen=set(); groups=[g for g in groups if not (g.name in seen or seen.add(g.name))]
3. Give custom groups a distinct name in the ToolGroup constructor, e.g. ToolGroup(name='my-default', ...)

Example fix

// before
toolkit = Toolkit(tool_groups=[default_group, ToolGroup(name='default', tools=[...])])
// after
toolkit = Toolkit(tool_groups=[default_group, ToolGroup(name='extra', tools=[...])])

names = [g.name for g in tool_groups]
assert len(names) == len(set(names)), f'duplicate group names: {names}'
toolkit = Toolkit(tool_groups=tool_groups)

When it happens

Trigger: Constructing a Toolkit (or agent with tool_groups=...) where the list contains two ToolGroup objects with identical .name values, e.g. a default group plus a user-supplied group both named 'default'.

Common situations: Appending a custom group that inadvertently reuses the default group name; copying example code that already includes a built-in group; merging group lists from different config sources without de-duplicating.

Related errors

• Cannot find group '{group_name}' in toolkit, only {[_.name f
• The injection template must contain the '{runtime_state}' pl
• Bot '{bot_id}' already registered as channel '{existing}'.
• MCP {card.name!r} produced an invalid client: {e}
• DimensionPolicy: kind=ANY requires dimension=None, got dimen

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/d45ff4dfb1ed32da. Report an issue: GitHub.