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

Second branch of assert_valid_name in autogen_ext.models.azure._azure_ai_client: raised when a name passes the character check but exceeds 64 characters. Azure AI model/agent names are capped at 64 chars, so the client enforces the limit locally before the request.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/azure/_azure_ai_client.py:177

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


class AzureAIChatCompletionClient(ChatCompletionClient):
    """
    Chat completion client for models hosted on Azure AI Foundry or GitHub Models.
    See `here <https://learn.microsoft.com/en-us/azure/ai-studio/reference/reference-model-inference-chat-completions>`_ for more info.

    Args:
        endpoint (str): The endpoint to use. **Required.**
        credential (union, AzureKeyCredential, AsyncTokenCredential): The credentials to use. **Required**
        model_info (ModelInfo): The model family and capabilities of the model. **Required.**
        model (str): The name of the model. **Required if model is hosted on GitHub Models.**
        frequency_penalty: (optional,float)
        presence_penalty: (optional,float)
        temperature: (optional,float)
        top_p: (optional,float)
        max_tokens: (optional,int)

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Truncate the name to 64 characters at construction time
2. Use _normalize_name for LLM-provided names — it already applies [:64]
3. Switch to short stable slugs (id-based) for internal names and keep long names in display metadata

Example fix

# before
name = f"{team_name}_{role}_{task_id}_worker"  # may exceed 64 chars

# after
name = f"{team_name}_{role}_{task_id}_worker"[:64]

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

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

When it happens

Trigger: Any message source or validated name longer than 64 characters, e.g. auto-generated names that concatenate team name + role + suffix, or names built from document titles.

Common situations: Multi-agent frameworks composing long deterministic names; names derived from user input or file names; LLM-generated identifiers that were never truncated.

Related errors

• Invalid name: {name}. Only letters, numbers, '_' and '-' are
• BING_API_KEY environment variable is not set
• Please set AZURE_OPENAI_API_KEY environment variable.
• Please set AZURE_OPENAI_ENDPOINT environment variable.
• Please set environment variable AZURE_OPENAI_API_KEY

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