mlflow/mlflow · error · MlflowException

Unknown tool type: {tool_type}

Error message

Unknown tool type: {tool_type}

What it means

When converting OpenAI chat tool definitions to MLflow span chat attributes, each tool's 'type' field must be a recognized kind (e.g., 'function'). Any other type string has no defined mapping, so _parse_tools raises this MlflowException.

Source

Thrown at mlflow/openai/utils/chat_schema.py:127

                # Responses API style
                definition = {k: v for k, v in tool.items() if k != "type"}
                parsed_tools.append(
                    ChatTool(
                        type="function",
                        function=FunctionToolDefinition(**definition),
                    )
                )
        elif tool_type in _RESPONSE_API_BUILT_IN_TOOLS:
            parsed_tools.append(
                ChatTool(
                    type="function",
                    function=FunctionToolDefinition(
                        name=tool_type,
                    ),
                )
            )
        else:
            raise MlflowException(f"Unknown tool type: {tool_type}")

    return parsed_tools


def _parse_model(output: Any) -> str | None:
    """
    Parse model information from OpenAI response objects.

    Args:
        output: The response object from OpenAI API calls

    Returns:
        The model name.
    """
    if output is None:
        return None

    # Handle OpenAI ChatCompletion API response

View on GitHub (pinned to 6a27f2decc)

Solutions

  1. Upgrade MLflow to a version that supports the new tool type
  2. Normalize tool definitions to supported types (e.g., convert to {'type': 'function', 'function': {...}}) before calling set_span_chat_attributes
  3. Skip or filter unsupported tools from the payload before setting span attributes

Example fix

// before
span_attrs_tools = [{"type": "custom_tool", ...}]
set_span_chat_attributes(span, output)  # raises

// after
tools = [{"type": "function", "function": {"name": "get_weather", ...}}]
set_span_chat_attributes(span, {**output, "tools": tools})
Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_TOOL_TYPES = {"function"}
def validate_tools(tools):
    for t in tools or []:
        if t.get("type") not in SUPPORTED_TOOL_TYPES:
            raise ValueError(f"Tool type {t.get('type')!r} not supported by set_span_chat_attributes")

Type guard

def is_supported_tool(tool: dict) -> bool:
    return isinstance(tool, dict) and tool.get("type") == "function"

Try / catch

from mlflow.exceptions import MlflowException
try:
    set_span_chat_attributes(span, output)
except MlflowException as e:
    if "Unknown tool type" in str(e):
        output["tools"] = [t for t in output.get("tools", []) if t.get("type") == "function"]
        set_span_chat_attributes(span, output)
    else:
        raise

Prevention

When it happens

Trigger: Calling mlflow.openai.utils.chat_schema.set_span_chat_attributes() (which calls _parse_tools) with response/tool payload whose tools include a type outside the supported set — e.g., a custom tool type, a newer OpenAI tool type not yet handled, or a malformed tools list where 'type' is arbitrary.

Common situations: Tracing newer OpenAI tool types (e.g., custom/hosted tools) that this MLflow version doesn't map yet; passing hand-built tool dicts with misspelled or invented 'type' values; proxying non-OpenAI APIs that emit their own tool types.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/8b8cc2c9438c9cca. Report an issue: GitHub.