`approximate_summary_tokens` must be a positive number of to

Error message

`approximate_summary_tokens` must be a positive number of tokens, got {approximate_summary_tokens}.

What it means

SummarizationCompactor also requires approximate_summary_tokens >= 1 (haystack/hooks/compaction/summarization.py:233); it uses this estimate when building the summarization prompt. Zero or negative values would produce an invalid token budget.

Source

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

: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.
:param token_counter: The counter used both to plan compaction and verify generated summaries.
:returns: A smaller replacement conversation, or None when nothing was reduced.

View on GitHub (pinned to e318778c9b)

Solutions

Set approximate_summary_tokens to a realistic positive estimate, e.g. 512.
Clamp: approximate_summary_tokens = max(1, value).
Provide a default (e.g. 500-1000 tokens) in config when unset.

Example fix

// before
compactor = SummarizationCompactor(chat_generator=g, approximate_summary_tokens=0)
// after
compactor = SummarizationCompactor(chat_generator=g, approximate_summary_tokens=512)

Defensive patterns

Strategy: validation

Validate before calling

def validate_summary_tokens(v):
    if not isinstance(v, int) or v < 1:
        raise ValueError(f"approximate_summary_tokens must be >= 1, got {v!r}")
validate_summary_tokens(cfg.get("approximate_summary_tokens", 512))

Type guard

def is_positive_int(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

Try / catch

try:
    compactor = SummarizationCompactor(chat_generator=gen, approximate_summary_tokens=t)
except ValueError as e:
    logger.error("bad approximate_summary_tokens: %s", e)
    compactor = SummarizationCompactor(chat_generator=gen, approximate_summary_tokens=512)

Prevention

Never use 0 as an 'auto' placeholder; pick a real budget like 512
Read env/config with a non-zero default
Validate alongside min_keep_steps before construction

When it happens

Trigger: Constructing SummarizationCompactor with approximate_summary_tokens=0 or negative, or a None/empty config value coerced to 0.

Common situations: Placeholder 0 meant to be 'auto'; reading the value from an unset env var; misconfigured summary-length settings.

Related errors

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