microsoft/autogen · error · ValueError

tail_size must be greater than 0.

Error message

tail_size must be greater than 0.

What it means

The second validation in HeadAndTailChatCompletionContext.__init__: after head_size passes, tail_size <= 0 raises ValueError. The tail holds the most recent tail_size messages, and a zero tail would make the context return effectively nothing useful, so the constructor refuses it. If you see this specific message, head_size was already valid.

Source

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

    """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]

        tail_messages = self._messages[-self._tail_size :]
        # Handle the first message is a function call result message.

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass tail_size >= 1.
2. Guard budget-derived values: `tail = max(1, budget // avg_msg_tokens)`.
3. Consider TokenLimitedChatCompletionContext when the real goal is token-budget trimming rather than fixed counts.

Example fix

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

# after
ctx = HeadAndTailChatCompletionContext(head_size=1, tail_size=20)

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

When it happens

Trigger: `HeadAndTailChatCompletionContext(head_size=1, tail_size=0)` or negative tail; computed tail sizes (e.g. from remaining token budget) hitting 0 for cheap models/short histories.

Common situations: Token-budget arithmetic that can round to 0; configs reusing a single 'size' knob for both parameters where it is 0; migrating from BufferedChatCompletionContext(buffer_size=0) code paths.

Related errors

• buffer_size must be greater than 0.
• head_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/69abf5cdfc016803. Report an issue: GitHub.