run-llama/llama_index · error · ValueError

Calculated available context size {context_size_tokens} was

Error message

Calculated available context size {context_size_tokens} was not non-negative.

What it means

PromptHelper._get_available_context_size computes context_window - num_prompt_tokens - num_output and raises when the result is negative. It means the prompt you already built plus the tokens reserved for the model output exceed the configured context window, leaving negative room for any content.

Source

Thrown at llama-index-core/llama_index/core/indices/prompt_helper.py:161

    def class_name(cls) -> str:
        return "PromptHelper"

    def _get_available_context_size(self, num_prompt_tokens: int) -> int:
        """
        Get available context size.

        This is calculated as:
            available context window = total context window
                - input (partially filled prompt)
                - output (room reserved for response)

        Notes:
        - Available context size is further clamped to be non-negative.

        """
        context_size_tokens = self.context_window - num_prompt_tokens - self.num_output
        if context_size_tokens < 0:
            raise ValueError(
                f"Calculated available context size {context_size_tokens} was"
                " not non-negative."
            )
        return context_size_tokens

    def _get_tools_from_llm(
        self, llm: Optional[LLM] = None, tools: Optional[List["BaseTool"]] = None
    ) -> List["BaseTool"]:
        from llama_index.core.program.function_program import get_function_tool

        tools = tools or []
        if isinstance(llm, StructuredLLM):
            tools.append(get_function_tool(llm.output_cls))

        return tools

    def _get_available_chunk_size(
        self,

View on GitHub (pinned to afd0fef371)

Solutions

1. Increase context_window (e.g. service_context = ServiceContext.from_defaults(llm=llm, context_window=8192)) or use a model with a larger window
2. Lower num_output so context_window - num_output leaves room for the prompt
3. Shorten the prompt template or reduce the number/format of few-shot examples
4. If the tokenizer is over-counting, supply the correct tokenizer via a custom num_output/token counter in PromptHelper

Example fix

# before
from llama_index.core import PromptHelper
helper = PromptHelper(context_window=2048, num_output=1536, chunk_overlap_ratio=0.1)

# after
helper = PromptHelper(context_window=8192, num_output=512, chunk_overlap_ratio=0.1)

from llama_index.core import PromptHelper
num_prompt_tokens = helper._token_counter(prompt)  # or llm.get_token_cnt(prompt)
if helper.context_window - num_prompt_tokens - helper.num_output < 0:
    raise ValueError('prompt + num_output exceeds context_window; shrink prompt or raise context_window')

try:
    splitter = prompt_helper.get_text_splitter(prompt, num_chunks)
except ValueError as e:
    if 'not non-negative' in str(e):
        # reconfigure with a larger window / smaller num_output and retry once
        prompt_helper = PromptHelper(context_window=8192, num_output=256)
    else:
        raise

When it happens

Trigger: Calling get_text_splitter / _get_available_chunk_size (directly or via index construction with a long prompt) where num_prompt_tokens + num_output > context_window. Typical with small context_window (e.g. 2048 for older models) combined with a large num_output (e.g. 1024+) or a verbose prompt template.

Common situations: Using a local/small-window model but leaving Settings.llm.num_output or PromptHelper defaults sized for large models; a very long system/custom prompt; a tokenizer mismatch that over-counts prompt tokens.

Related errors

• Chunk size {chunk_size} is not positive.
• EmptyIndex only supports response_mode=generation.
• Unknown retriever mode: {retriever_mode}
• Unknown retriever mode: {retriever_mode}
• No index in storage context, check if you specified the righ

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/0aa01498a9664e17. Report an issue: GitHub.