microsoft/autogen · error · ValueError

head_size must be greater than 0.

Error message

head_size must be greater than 0.

What it means

HeadAndTailChatCompletionContext validates both constructor size arguments; head_size <= 0 raises ValueError immediately. The head keeps the oldest head_size messages (typically the initial system prompt), so a non-positive head would silently drop the system messages — hence fail-fast at construction.

Source

Thrown at python/packages/autogen-core/src/autogen_core/model_context/_head_and_tail_chat_completion_context.py:35

class HeadAndTailChatCompletionContext(ChatCompletionContext, Component[HeadAndTailChatCompletionContextConfig]):
    """A chat completion context that keeps a view of the first n and last m messages,
    where n is the head size and m is the tail size. The head and tail sizes
    are set at initialization.

    Args:
        head_size (int): The size of the head.
        tail_size (int): The size of the tail.
        initial_messages (List[LLMMessage] | None): The initial messages.
    """

    component_config_schema = HeadAndTailChatCompletionContextConfig
    component_provider_override = "autogen_core.model_context.HeadAndTailChatCompletionContext"

    def __init__(self, head_size: int, tail_size: int, initial_messages: List[LLMMessage] | None = None) -> None:
        super().__init__(initial_messages)
        if head_size <= 0:
            raise ValueError("head_size must be greater than 0.")
        if tail_size <= 0:
            raise ValueError("tail_size must be greater than 0.")
        self._head_size = head_size
        self._tail_size = tail_size

    async def get_messages(self) -> List[LLMMessage]:
        """Get at most `head_size` recent messages and `tail_size` oldest messages."""
        head_messages = self._messages[: self._head_size]
        # Handle the last message is a function call message.
        if (
            head_messages
            and isinstance(head_messages[-1], AssistantMessage)
            and isinstance(head_messages[-1].content, list)
            and all(isinstance(item, FunctionCall) for item in head_messages[-1].content)
        ):
            # Remove the last message from the head.
            head_messages = head_messages[:-1]

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass head_size >= 1; a typical value is 1 to preserve just the system message.
2. If you intended 'keep everything recent only', use BufferedChatCompletionContext(tail) semantics instead.
3. Clamp computed budgets with max(1, value).

Example fix

# before
ctx = HeadAndTailChatCompletionContext(head_size=0, tail_size=10)  # ValueError

# after
ctx = HeadAndTailChatCompletionContext(head_size=1, tail_size=10)  # keep system message + last 10

if not (isinstance(head_size, int) and head_size >= 1):
    raise ValueError("head_size must be a positive integer")

When it happens

Trigger: `HeadAndTailChatCompletionContext(head_size=0, tail_size=5)` or a negative/computed head_size that lands at 0. Distinct from error 596: this one names head_size, meaning the head argument failed validation first.

Common situations: Configs where 0 means 'no head' — not supported; deriving head_size from token budgets that compute to 0 for short prompts; copy-paste of the tail_size value into both parameters during refactor.

Related errors

• buffer_size must be greater than 0.
• tail_size must be greater than 0.
• token_limit must be greater than 0.
• Missing required field '{field}' in ModelInfo. Starting in v
• Maximum number of tool iterations must be greater than or eq

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