agentscope-ai/agentscope · error · ValueError

The 'reserve_ratio' of the context config must be smaller th

Error message

The 'reserve_ratio' of the context config must be smaller than its 'trigger_ratio', got {self.context_config.reserve_ratio} and {self.context_config.trigger_ratio}.

What it means

During Agent __init__ validation: the context compression config requires reserve_ratio to be strictly smaller than trigger_ratio. reserve_ratio is the fraction of the context preserved after compression; if it is >= the ratio that triggers compression, compression could never free enough space, so the agent refuses to start.

Source

Thrown at src/agentscope/agent/_agent.py:232

        # Set when a `ReplyEndEvent` escapes the reply middleware chain; the
        # reply loop only exits after the event is delivered (not swallowed)
        self._receive_reply_end: bool = False

    def _validate_configs(self) -> None:
        """Validate the config combinations that a single config class cannot
        check by itself.

        Raises:
            `ValueError`:
                If the reserved/buffer ratios don't leave room ahead of the
                context compression threshold.
        """
        if (
            self.context_config.reserve_ratio
            >= self.context_config.trigger_ratio
        ):
            raise ValueError(
                "The 'reserve_ratio' of the context config must be smaller "
                "than its 'trigger_ratio', got "
                f"{self.context_config.reserve_ratio} and "
                f"{self.context_config.trigger_ratio}.",
            )

        if (
            self.injection_config.inject_runtime_state
            and self.injection_config.context_buffer_ratio
            >= self.context_config.trigger_ratio
        ):
            raise ValueError(
                "The 'context_buffer_ratio' of the injection config must be "
                "smaller than the 'trigger_ratio' of the context config, so "
                "that the context length is injected before the compression, "
                f"got {self.injection_config.context_buffer_ratio} and "
                f"{self.context_config.trigger_ratio}.",
            )

View on GitHub (pinned to e90f1c7592)

Solutions

1. Set reserve_ratio strictly below trigger_ratio, e.g. reserve_ratio=0.2, trigger_ratio=0.5
2. If you lowered trigger_ratio, lower reserve_ratio to match (rule of thumb: reserve ≈ half of trigger)
3. Add an assertion/normalization step in your config loader so misordered ratios fail fast with a clear message

Example fix

# before
agent = ReActAgent(
    context_config=ContextConfig(trigger_ratio=0.4, reserve_ratio=0.5),
)

# after
agent = ReActAgent(
    context_config=ContextConfig(trigger_ratio=0.5, reserve_ratio=0.2),
)

def make_context_config(trigger: float, reserve: float) -> ContextConfig:
    if not 0 < reserve < trigger <= 1:
        raise ValueError(
            f"Need 0 < reserve_ratio < trigger_ratio <= 1, got reserve={reserve}, trigger={trigger}"
        )
    return ContextConfig(trigger_ratio=trigger, reserve_ratio=reserve)

agent = ReActAgent(context_config=make_context_config(0.5, 0.2))

from typing import TypeGuard

def valid_context_ratios(trigger: float, reserve: float) -> TypeGuard[float]:
    return 0 < reserve < trigger <= 1

try:
    agent = ReActAgent(context_config=cfg)
except ValueError as e:
    if "reserve_ratio" in str(e):
        cfg.reserve_ratio = cfg.trigger_ratio / 2
        agent = ReActAgent(context_config=cfg)
    else:
        raise

When it happens

Trigger: Constructing an Agent (or calling _validate_configs via __init__) with ContextConfig(reserve_ratio=0.5, trigger_ratio=0.4) or equal values (0.5, 0.5). The check is >=, so equality is also rejected.

Common situations: Tuning context-compression ratios without realizing the ordering constraint; defaults changed across versions; copying config examples where ratios were swapped; setting trigger_ratio low (e.g. 0.1) while leaving reserve_ratio at a default above it.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• The 'context_buffer_ratio' of the injection config must be s
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• The system prompt {suffix}exceed(s) the compression threshol
• factory must be a callable, got {type(factory).__name__}
• Agent did not produce a final message.

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/84291c122f731607. Report an issue: GitHub.