microsoft/autogen · error · ValueError

Invalid name: {name}. Name must be less than 64 characters.

Error message

Invalid name: {name}. Name must be less than 64 characters.

What it means

The second rule of assert_valid_name(): after passing the character-set check, a name longer than 64 characters raises ValueError. Names are capped at 64 chars to stay compatible with the Ollama/OpenAI tool-name limits (the companion _normalize_name truncates to [:64]).

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/ollama/_ollama_client.py:369

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


# TODO: Does this need to change?
def normalize_stop_reason(stop_reason: str | None) -> FinishReasons:
    if stop_reason is None:
        return "unknown"

    # Convert to lower case
    stop_reason = stop_reason.lower()

    KNOWN_STOP_MAPPINGS: Dict[str, FinishReasons] = {
        "stop": "stop",
        "end_turn": "stop",
        "tool_calls": "function_calls",
    }

    return KNOWN_STOP_MAPPINGS.get(stop_reason, "unknown")

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Shorten the name to <= 64 characters (abbreviate the most redundant segment)
2. For generated names, truncate before asserting: name = name[:64]
3. If the name comes from LLM output, use _normalize_name() which truncates automatically

Example fix

# before
name = "very_long_auto_generated_tool_name_" + uuid4().hex  # > 64 chars
assert_valid_name(name)

# after
name = ("very_long_auto_generated_tool_name_" + uuid4().hex)[:64]
assert_valid_name(name)

name = name[:64]
assert_valid_name(name)  # now safe on length

def name_within_limit(name: str) -> bool:
    return 0 < len(name) <= 64

try:
    assert_valid_name(name)
except ValueError as e:
    if "less than 64" in str(e):
        name = name[:64]
    else:
        raise

When it happens

Trigger: Registering a tool or component whose name is 65+ characters — typically auto-generated names like 'agent_team_step_...' built by concatenating scopes, ids, and verbs.

Common situations: Programmatic name generation from class paths or sentence descriptions; long descriptive agent names in group chat configs; names built by joining namespace prefixes.

Related errors

• Invalid name: {name}. Only letters, numbers, '_' and '-' are
• The from field must be null or the agent name
• Invalid Role
• The agent name must be a valid Python identifier.
• The participant names must be unique.

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