run-llama/llama_index · error · ValueError

Program factory not supported without structured answer filt

Error message

Program factory not supported without structured answer filtering.

What it means

Refine's structured answer filtering uses a program (a structured LLM extractor) to decide whether a refined answer actually improved. Passing program_factory only makes sense in that flow, so Refine.__init__ raises ValueError when program_factory is not None but structured_answer_filtering=False. Note program_factory defaults to _default_program_factory when omitted.

Source

Thrown at llama-index-core/llama_index/core/response_synthesizers/refine.py:248

            chat_prompt_helper=chat_prompt_helper,
            streaming=streaming,
            multimodal=multimodal,
        )
        self._text_qa_template = text_qa_template or DEFAULT_TEXT_QA_PROMPT_SEL
        self._refine_template = refine_template or DEFAULT_REFINE_PROMPT_SEL
        self._chat_content_qa_template = (
            chat_content_qa_template or CHAT_CONTENT_QA_PROMPT
        )
        self._chat_content_refine_template = (
            chat_content_refine_template or CHAT_CONTENT_REFINE_PROMPT
        )
        self._verbose = verbose
        self._structured_answer_filtering = structured_answer_filtering
        self._output_cls = output_cls
        self._response_padding_size = response_padding_size

        if not self._structured_answer_filtering and program_factory is not None:
            raise ValueError(
                "Program factory not supported without structured answer filtering."
            )
        self._program_factory = program_factory or self._default_program_factory

    def _get_prompts(self) -> PromptDictType:
        """Get prompts."""
        return {
            "text_qa_template": self._text_qa_template,
            "refine_template": self._refine_template,
            "chat_content_qa_template": self._chat_content_qa_template,
            "chat_content_refine_template": self._chat_content_refine_template,
        }

    def _update_prompts(self, prompts: PromptDictType) -> None:
        """Update prompts."""
        if "text_qa_template" in prompts:
            self._text_qa_template = prompts["text_qa_template"]
        if "refine_template" in prompts:

View on GitHub (pinned to afd0fef371)

Solutions

1. Set structured_answer_filtering=True if you want to use the program factory.
2. Or drop the program_factory argument entirely when running with structured_answer_filtering=False.

Example fix

# before
synth = Refine(
    program_factory=my_factory,
    structured_answer_filtering=False,
)

# after
synth = Refine(
    program_factory=my_factory,
    structured_answer_filtering=True,
)

if program_factory is not None:
    assert structured_answer_filtering, "program_factory requires structured_answer_filtering=True"

When it happens

Trigger: Constructing Refine(program_factory=my_factory, structured_answer_filtering=False); copying config from a refine setup that had structured filtering on, then disabling the flag but keeping the factory; toggling structured_answer_filtering off to save tokens while leaving a program factory in place.

Common situations: Config-driven synthesizer setup where the two options are set independently; refactors that flip the flag without cleaning the factory argument.

Related errors

• Unable to stream in Accumulate response mode
• Multimodal synthesis requires a chat LLM.
• Unknown mode: {response_mode}
• Root id {root_id} not in retriever_dict, it must be a retrie
• embed_model must start with str 'local' or of type BaseEmbed

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