microsoft/autogen · error · ValueError

Invalid name: {name}. Only letters, numbers, '_' and '-' are

Error message

Invalid name: {name}. Only letters, numbers, '_' and '-' are allowed.

What it means

Raised by assert_valid_name in autogen_ext.models.llama_cpp._llama_cpp_completion_client when a name contains characters outside [a-zA-Z0-9_-] (regex ^[a-zA-Z0-9_-]+$). llama-cpp server tooling requires this name charset, so the local client validates message sources / tool names before conversion; _normalize_name is the munging counterpart for LLM-generated names.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/llama_cpp/_llama_cpp_completion_client.py:77

def normalize_name(name: str) -> str:
    """
    LLMs sometimes ask functions while ignoring their own format requirements, this function should be used to replace invalid characters with "_".

    Prefer _assert_valid_name for validating user configuration or input
    """
    return re.sub(r"[^a-zA-Z0-9_-]", "_", name)[:64]


def assert_valid_name(name: str) -> str:
    """
    Ensure that configured names are valid, raises ValueError if not.

    For munging LLM responses use _normalize_name to ensure LLM specified names don't break the API.
    """
    if not re.match(r"^[a-zA-Z0-9_-]+$", name):
        raise ValueError(f"Invalid name: {name}. Only letters, numbers, '_' and '-' are allowed.")
    if len(name) > 64:
        raise ValueError(f"Invalid name: {name}. Name must be less than 64 characters.")
    return name


def convert_tools(
    tools: Sequence[Tool | ToolSchema],
) -> List[ChatCompletionTool]:
    result: List[ChatCompletionTool] = []
    for tool in tools:
        if isinstance(tool, Tool):
            tool_schema = tool.schema
        else:
            assert isinstance(tool, dict)
            tool_schema = tool

        result.append(
            ChatCompletionTool(

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Rename tools/agents to only letters, digits, '_' and '-'
2. For LLM-emitted names, sanitize with the module's _normalize_name before use
3. Validate names once at registration time, not per request

Example fix

# before
tool = Tool(name="get.weather", description="...", run=fn)

# after
tool = Tool(name="get_weather", description="...", run=fn)

import re

def tool_name_ok(name: str) -> bool:
    return bool(re.fullmatch(r"[a-zA-Z0-9_-]+", name)) and len(name) <= 64

import re

def is_valid_tool_name(name: str) -> bool:
    return re.fullmatch(r"[a-zA-Z0-9_-]{1,64}", name) is not None

When it happens

Trigger: Passing a tool with a name like 'get.weather' or a message source with spaces/unicode to LlamaCppChatCompletionClient.create()/create_stream(); LLM hallucinating a function name with dots or parentheses (should be normalized, not asserted).

Common situations: Tool schemas authored with dotted names; agent names copied from display labels; multi-agent runs where the same UserMessage sources used elsewhere are reused against llama.cpp.

Related errors

• Invalid name: {name}. Name must be less than 64 characters.
• Invalid name: {name}. Only letters, numbers, '_' and '-' are
• Missing ANTHROPIC_API_KEY environment variable.
• The model does not support function calling.
• Unsupported tool type: {type(tool)}

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/020c1f8b34bf4786. Report an issue: GitHub.