oraios/serena · error · ValueError

Tool named '{tool_name}' not found.

Error message

Tool named '{tool_name}' not found.

What it means

ToolRegistry.get_tool_class_by_name looks up a registered tool class by its tool_name; if the name is absent from the registry's internal tool dictionary it raises ValueError. This guards callers (e.g. get_tool_by_name) against requesting tools that were never registered or were disabled/deleted.

Source

Thrown at src/serena/tools/tools_base.py:623

    def get_registered_tools_by_module(self) -> dict[str, list[RegisteredTool]]:
        """
        :return: the registered tools grouped by their module (ordered alphabetically by module and tool name)
        """
        module_dict: dict[str, list[RegisteredTool]] = {}
        for tool in self._tool_dict.values():
            module = tool.tool_class.__module__
            if module not in module_dict:
                module_dict[module] = []
            module_dict[module].append(tool)
        sorted_module_dict = {}
        for module in sorted(module_dict.keys()):
            sorted_module_dict[module] = sorted(module_dict[module], key=lambda t: t.tool_name)
        return sorted_module_dict

    def get_tool_class_by_name(self, tool_name: str) -> type[Tool]:
        if tool_name not in self._tool_dict:
            raise ValueError(f"Tool named '{tool_name}' not found.")
        return self._tool_dict[tool_name].tool_class

    def get_all_tool_classes(self) -> list[type[Tool]]:
        return list(t.tool_class for t in self._tool_dict.values())

    def get_tool_classes_default_enabled(self) -> list[type[Tool]]:
        """
        :return: the list of tool classes that are enabled by default (i.e. non-optional tools).
        """
        return [t.tool_class for t in self._tool_dict.values() if not t.is_optional]

    def get_tool_classes_optional(self) -> list[type[Tool]]:
        """
        :return: the list of tool classes that are optional (i.e. disabled by default).
        """
        return [t.tool_class for t in self._tool_dict.values() if t.is_optional]

    def get_tool_names_default_enabled(self) -> list[str]:

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Check available names with registry.get_all_tool_names() (or list of registered tools) and correct the spelling
2. Verify the tool's module is actually registered with the registry instance being used
3. If the tool was intentionally removed, update the calling code/config to a replacement tool name
4. Wrap the lookup in try/except ValueError and fall back to a default tool

Example fix

// before
tool_cls = registry.get_tool_class_by_name('read_fiel')
// after
names = registry.get_all_tool_names()
assert 'read_file' in names, names
tool_cls = registry.get_tool_class_by_name('read_file')

if tool_name in registry.get_all_tool_names():
    tool_cls = registry.get_tool_class_by_name(tool_name)
else:
    log.warning(f"{tool_name} not registered")

def is_registered_tool(registry, name: str) -> bool:
    return name in registry.get_all_tool_names()

try:
    tool_cls = registry.get_tool_class_by_name(tool_name)
except ValueError:
    tool_cls = None  # or fall back to a default tool

When it happens

Trigger: Calling get_tool_class_by_name or get_tool_by_name with a tool name string that is not a key in the registry's _tool_dict — e.g. a misspelled tool name, a tool from a module not registered, or a name referencing a tool removed/disabled in the active configuration.

Common situations: Agents or configs referencing tools by hardcoded names after a Serena version renamed tools; requesting tool classes for tools excluded by context (e.g. without_editing_tools variants); typos in tool names in YAML/config files.

Related errors

• Invalid tool name: {tool_name}{caller_context_for_logging}
• Invalid topic: {topic}
• Pass either content or source_file_path
• Invalid glob brace expression in {pattern!r}: empty braces a
• Invalid glob brace expression in {pattern!r}: unmatched brac

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/e086918da8c6e575. Report an issue: GitHub.