BerriAI/litellm · error · ValueError

Top-level function names conflict with flattened namespace t

Error message

Top-level function names conflict with flattened namespace tools: {conflicting_tool_names}

What it means

Collision guard when flattening Responses-API namespace tools: one or more generated '<tool>__<subtool>' flattened names are identical to a top-level function tool's name, which would make the tool namespace ambiguous; the conflicting names are listed in the message.

Source

Thrown at litellm/responses/litellm_completion_transformation/transformation.py:1476

        return (flat_tool,) if flat_tool is not None else ()

    @staticmethod
    def _validate_namespace_name_collisions(tools: ResponseTools) -> None:
        top_level_function_names: Final = frozenset(
            str(tool.get("name") or "") for tool in tools or () if tool.get("type") == "function"
        )
        flattened_namespace_names: Final = frozenset(
            f"{(tool.get('name') or '')!s}__{(namespace_tool.get('name') or '')!s}"
            for tool in tools or ()
            if tool.get("type") == "namespace"
            for namespace_tools in (tool.get("tools"),)
            if isinstance(namespace_tools, Sequence) and not isinstance(namespace_tools, (str, bytes))
            for namespace_tool in namespace_tools
            if isinstance(namespace_tool, Mapping) and namespace_tool.get("type") == "function"
        )
        conflicting_tool_names: Final = top_level_function_names & flattened_namespace_names
        if conflicting_tool_names:
            raise ValueError(
                "Top-level function names conflict with flattened namespace tools: "
                + ", ".join(sorted(conflicting_tool_names))
            )

    @staticmethod
    def transform_responses_api_tools_to_chat_completion_tools(
        tools: list[FunctionToolParam | OpenAIMcpServerTool] | None,
    ) -> tuple[
        list[ChatCompletionToolParam | OpenAIMcpServerTool],
        OpenAIWebSearchOptions | None,
    ]:
        """
        Transform a Responses API tools into a Chat Completion tools
        """
        if tools is None:
            return [], None
        LiteLLMCompletionResponsesConfig._validate_namespace_name_collisions(tools)
        chat_completion_tools: Final[list[ChatCompletionToolParam | OpenAIMcpServerTool]] = []

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Rename conflicting tools so top-level function names don't clash with flattened namespace tool names.

When it happens

Trigger: Thrown at litellm/responses/litellm_completion_transformation/transformation.py:1476 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/3daf68feb73a5113. Report an issue: GitHub.