deepset-ai/haystack · error

`min_keep_steps` must be at least 0, got {min_keep_steps}.

Error message

`min_keep_steps` must be at least 0, got {min_keep_steps}.

What it means

SummarizationCompactor validates min_keep_steps in __init__ (haystack/hooks/compaction/summarization.py:231) and raises ValueError for negative values. min_keep_steps guarantees the most recent steps are never summarized away; negative values are invalid.

Source

Thrown at haystack/hooks/compaction/summarization.py:231

        :param chat_generator: The Chat Generator used to write summaries.
        :param min_keep_steps: The fewest complete recent Agent steps to keep, even when they exceed the target.
        :param approximate_summary_tokens: About how long you expect a summary to come out. This is an estimate used
            for planning, not a limit imposed on the model. The compactor uses it to work out how much of the
            conversation to summarize. A higher value causes the compactor to summarize more of the conversation per
            round, so the result is likelier to land under the target, at the cost of giving up more of the
            conversation. A lower value summarizes less per round and keeps more, but may leave the result above the
            target.
        :param summary_instruction: The prompt instructions for how to summarize a portion of the conversation.
            The default instructions ask for a summary with fixed sections covering the objective, decisions and
            constraints, completed work, exact identifiers, and unresolved work.
        :param raise_on_failure: Whether to raise an exception if the chat generator fails or returns a summary that
            does not shrink the conversation. By default the failure is logged and any successful partial compaction
            is returned.
        :raises ValueError: If `min_keep_steps` is negative or `approximate_summary_tokens` is not positive.
        """
        if min_keep_steps < 0:
            raise ValueError(f"`min_keep_steps` must be at least 0, got {min_keep_steps}.")
        if approximate_summary_tokens < 1:
            raise ValueError(
                f"`approximate_summary_tokens` must be a positive number of tokens, got {approximate_summary_tokens}."
            )
        self.chat_generator = chat_generator
        self.min_keep_steps = min_keep_steps
        self.approximate_summary_tokens = approximate_summary_tokens
        self.summary_instruction = summary_instruction
        self.raise_on_failure = raise_on_failure

    def compact(
        self, messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
    ) -> list[ChatMessage] | None:
        """
        Return a progressively summarized conversation, or None when no useful reduction is possible.

        :param messages: The conversation to compact, ordered oldest to newest.
        :param target_tokens: The token budget the compacted messages should aim to fit.

View on GitHub (pinned to e318778c9b)

Solutions

  1. Pass min_keep_steps >= 0.
  2. Clamp: min_keep_steps = max(0, value) before constructing.
  3. Correct the upstream config/env value.

Example fix

// before
compactor = SummarizationCompactor(chat_generator=g, min_keep_steps=-1)
// after
compactor = SummarizationCompactor(chat_generator=g, min_keep_steps=2)
Defensive patterns

Strategy: validation

Validate before calling

def validate_min_keep_steps(v):
    if not isinstance(v, int) or v < 0:
        raise ValueError(f"min_keep_steps must be >= 0, got {v!r}")
validate_min_keep_steps(cfg.get("min_keep_steps", 2))

Type guard

def is_non_negative_int(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 0

Try / catch

try:
    compactor = SummarizationCompactor(chat_generator=gen, min_keep_steps=n)
except ValueError as e:
    logger.error("bad min_keep_steps: %s", e)
    compactor = SummarizationCompactor(chat_generator=gen, min_keep_steps=2)

Prevention

When it happens

Trigger: Constructing SummarizationCompactor with min_keep_steps < 0, often from a computed or config-supplied value.

Common situations: Arithmetic on a keep-count that underflows below zero; typos like min_keep_steps=-2 in example configs; changing defaults by subtraction.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/cfcf9ba7ef2e645c. Report an issue: GitHub.