What causes "fail to reduce message length" in FoundationAgents/MetaGPT?

Use a model with a larger context window (present in TOKEN_MAX), e.g. a gpt-4-class or claude-class model name.

FoundationAgents/MetaGPT · error · RuntimeError

fail to reduce message length

Error message

fail to reduce message length

What it means

Raised by metagpt.utils.text.reduce_message_length: it computes a per-model token budget (TOKEN_MAX[model_name] minus system-text tokens minus reserved) and returns the first message that fits; if every candidate message still exceeds the budget, reduction has failed and RuntimeError is raised rather than silently returning an oversized message.

Source

Thrown at metagpt/utils/text.py:31

    Args:
        msgs: A generator of strings representing progressively shorter valid prompts.
        model_name: The name of the encoding to use. (e.g., "gpt-3.5-turbo")
        system_text: The system prompts.
        reserved: The number of reserved tokens.

    Returns:
        The concatenated message segments reduced to fit within the maximum token size.

    Raises:
        RuntimeError: If it fails to reduce the concatenated message length.
    """
    max_token = TOKEN_MAX.get(model_name, 2048) - count_output_tokens(system_text, model_name) - reserved
    for msg in msgs:
        if count_output_tokens(msg, model_name) < max_token or model_name not in TOKEN_MAX:
            return msg

    raise RuntimeError("fail to reduce message length")


def generate_prompt_chunk(
    text: str,
    prompt_template: str,
    model_name: str,
    system_text: str,
    reserved: int = 0,
) -> Generator[str, None, None]:
    """Split the text into chunks of a maximum token size.

    Args:
        text: The text to split.
        prompt_template: The template for the prompt, containing a single `{}` placeholder. For example, "### Reference\n{}".
        model_name: The name of the encoding to use. (e.g., "gpt-3.5-turbo")
        system_text: The system prompts.
        reserved: The number of reserved tokens.

View on GitHub (pinned to 11cdf466d0)

Solutions

Use a model with a larger context window (present in TOKEN_MAX), e.g. a gpt-4-class or claude-class model name.
Shrink the inputs: shorter system_text, smaller reserved value, or pre-truncate/split the messages before calling.
Split the content with generate_prompt_chunk and process it in chunks instead of trying to fit one message.
Ensure msgs are ordered/curated so at least one candidate fits (drop the largest ones).

Example fix

# before
msg = reduce_message_length(msgs, 'gpt-35-turbo', LONG_SYSTEM, reserved=2000)  # RuntimeError

# after
from metagpt.utils.text import generate_prompt_chunk
for chunk in generate_prompt_chunk(big_text, PROMPT_TPL, 'gpt-4o', SHORT_SYSTEM):
    ...  # process each fitting chunk

Defensive patterns

Strategy: fallback

Validate before calling

from metagpt.utils.token_counter import count_output_tokens
from metagpt.utils.text import TOKEN_MAX
budget = TOKEN_MAX.get(model_name, 2048) - count_output_tokens(system_text, model_name) - reserved
if msgs and count_output_tokens(msgs[-1], model_name) >= budget:
    raise ValueError('messages exceed model budget; chunk first')

Type guard

def fits_in_budget(msg: str, model_name: str, system_text: str, reserved: int = 0) -> bool:
    if model_name not in TOKEN_MAX:
        return True
    budget = TOKEN_MAX[model_name] - count_output_tokens(system_text, model_name) - reserved
    return count_output_tokens(msg, model_name) < budget

Try / catch

from metagpt.utils.text import generate_prompt_chunk
try:
    msg = reduce_message_length(msgs, model_name, system_text, reserved)
except RuntimeError:
    # fall back to chunked processing instead of one oversized message
    for chunk in generate_prompt_chunk(big_text, template, model_name, system_text):
        handle(chunk)

Prevention

Pick a model whose TOKEN_MAX entry fits system_text + reserved + payload.
Trim system_text and reserved before large payloads.
Chunk long inputs up front with generate_prompt_chunk; don't rely on reduce to shrink untrimmable blobs.
Verify model_name is a known key in TOKEN_MAX before relying on reduction.

When it happens

Trigger: Calling reduce_message_length(msgs, model_name, system_text, reserved) where every msg exceeds TOKEN_MAX[model_name]-2048-style budget, or model_name is unknown AND the first msg is huge (unknown models short-circuit the check via `model_name not in TOKEN_MAX`, but known small-window models like gpt-3.5 hit it), or reserved/system_text consume the whole budget.

Common situations: Feeding large documents/logs to a small-context model; system_text plus reserved tokens leaving almost no room; oversized single messages that cannot be trimmed because each candidate is one big blob.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/0b551e0f0c143d8d. Report an issue: GitHub.