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

Thrown by assert_valid_name in autogen_ext.models.openai._utils when a configured name contains characters outside [a-zA-Z0-9_-]. This validates developer-configured names (agent names, tool names) that go into API payloads, as opposed to LLM-generated names which are munged via _normalize_name instead.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/openai/_utils.py:11

import re


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

View on GitHub (pinned to 027ecf0a37)

Solutions

Rename to use only letters, digits, underscore, and hyphen: 'customer_support_agent'
Sanitize programmatically: re.sub(r'[^a-zA-Z0-9_-]', '_', name)
For LLM-produced names, use the provided _normalize_name helper instead of assert_valid_name

Example fix

# before
name = assert_valid_name("customer support.agent")  # ValueError

# after
import re
name = assert_valid_name(re.sub(r"[^a-zA-Z0-9_-]", "_", "customer support.agent"))  # 'customer_support_agent_'

Defensive patterns

Strategy: validation

Validate before calling

import re

def safe_name(name: str) -> str:
    return re.sub(r"[^a-zA-Z0-9_-]", "_", name)[:64]

name = safe_name(raw_name)  # guaranteed to pass assert_valid_name

Type guard

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

Try / catch

try:
    assert_valid_name(name)
except ValueError:
    name = re.sub(r"[^a-zA-Z0-9_-]", "_", name)
    assert_valid_name(name)

Prevention

Generate names through one sanitizer (regex [a-zA-Z0-9_-], truncate to 64) at the boundary
Never feed user input or file paths directly as tool/agent names
Add a startup assertion for all configured names so bad names fail at boot, not mid-run

When it happens

Trigger: Passing a name containing spaces, dots, slashes, unicode, or other symbols to assert_valid_name — e.g. an agent or tool named 'my tool.v2' or 'helper/agent'. The regex must fully match the whole string; empty strings also fail.

Common situations: Human-readable agent names ('Customer Support Agent') passed unmodified; tool names derived from Python dotted paths (module.function); names built from user input or file names without sanitization.

Related errors

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