run-llama/llama_index · error · OutputParserException

Failed to validate query spec. Error: {e}. Got JSON dict: {j

Error message

Failed to validate query spec. Error: {e}. Got JSON dict: {json_dict}

What it means

VectorStoreQueryOutputParser.parse raises OutputParserException(f'Failed to validate query spec. Error: {e}. Got JSON dict: {json_dict}') when the JSON it parsed out of the LLM output fails VectorStoreQuerySpec.model_validate. The spec requires query: str and filters: List[MetadataFilter] (each filter needing key/value/operator), so JSON missing 'query', with filters as strings instead of objects, or with wrong field types fails Pydantic validation. This parser sits inside VectorIndexAutoRetriever, converting the LLM's natural-language query into a structured query spec.

Source

Thrown at llama-index-core/llama_index/core/indices/vector_store/retrievers/auto_retriever/output_parser.py:17

from typing import Any

from pydantic import ValidationError

from llama_index.core.output_parsers.base import OutputParserException, StructuredOutput
from llama_index.core.output_parsers.utils import parse_json_markdown
from llama_index.core.types import BaseOutputParser
from llama_index.core.vector_stores.types import VectorStoreQuerySpec


class VectorStoreQueryOutputParser(BaseOutputParser):
    def parse(self, output: str) -> Any:
        json_dict = parse_json_markdown(output)
        try:
            query_and_filters = VectorStoreQuerySpec.model_validate(json_dict)
        except ValidationError as e:
            raise OutputParserException(
                f"Failed to validate query spec. Error: {e}. Got JSON dict: {json_dict}"
            ) from e

        return StructuredOutput(raw_output=output, parsed_output=query_and_filters)

    def format(self, prompt_template: str) -> str:
        return prompt_template

View on GitHub (pinned to afd0fef371)

Solutions

1. Use a stronger LLM or one with structured/function-calling output, and keep the default vector store query prompt.
2. If you customized prompt_template_str, make it demand exactly {"query": str, "filters": [{"key": str, "value": str, "operator": str}]} — the VectorStoreQuerySpec schema.
3. Catch OutputParserException at retriever.run/retrieve call time and retry the query once or fall back to a plain VectorIndexRetriever without auto filters.

Example fix

# before
retriever = VectorIndexAutoRetriever(index, llm=weak_llm)  # weak_llm emits {"filters": "category=science"}
nodes = retriever.retrieve("news about AI")  # OutputParserException

# after
retriever = VectorIndexAutoRetriever(index, llm=strong_llm)
try:
    nodes = retriever.retrieve("news about AI")
except OutputParserException:
    nodes = VectorIndexRetriever(index).retrieve("news about AI")  # fallback, no auto filters

from llama_index.core.output_parsers.utils import parse_json_markdown
from llama_index.core.vector_stores.types import VectorStoreQuerySpec

def llm_output_is_valid_spec(raw: str) -> bool:
    try:
        VectorStoreQuerySpec.model_validate(parse_json_markdown(raw))
        return True
    except Exception:
        return False

from llama_index.core.output_parsers.base import OutputParserException

try:
    nodes = auto_retriever.retrieve(query_str)
except OutputParserException:
    nodes = VectorIndexRetriever(index).retrieve(query_str)  # graceful degradation, no auto filters

When it happens

Trigger: Using VectorIndexAutoRetriever with an LLM whose JSON deviates from the VectorStoreQueryPrompt spec: {"query": "...", "filters": [{"key": ..., "value": ...}]}; models emitting filters as [{"category": "science"}] objects without key/value fields; empty or null filters field on weak models.

Common situations: Local/small models not following the output schema; a custom prompt_template_str for the auto retriever that drifted from the required JSON shape; LLM wrapping JSON in prose that parse_json_markdown partially mis-parses.

Related errors

• Invalid answer line: {answer_line}. Answer line must be of t
• extra_filters cannot be OR condition
• StructuredLLM expected a {self.output_cls.__name__} instance
• StructuredLLM expected a {self.output_cls.__name__} instance
• key should not be None

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