{"record":{"id":"43e18d60917dcc64","repo":"run-llama/llama_index","slug":"failed-to-validate-query-spec-error-e-got-jso","errorCode":null,"errorMessage":"Failed to validate query spec. Error: {e}. Got JSON dict: {json_dict}","messagePattern":"Failed to validate query spec\\. Error: (.+?)\\. Got JSON dict: (.+?)","errorType":"exception","errorClass":"OutputParserException","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/vector_store/retrievers/auto_retriever/output_parser.py","lineNumber":17,"sourceCode":"from typing import Any\n\nfrom pydantic import ValidationError\n\nfrom llama_index.core.output_parsers.base import OutputParserException, StructuredOutput\nfrom llama_index.core.output_parsers.utils import parse_json_markdown\nfrom llama_index.core.types import BaseOutputParser\nfrom llama_index.core.vector_stores.types import VectorStoreQuerySpec\n\n\nclass VectorStoreQueryOutputParser(BaseOutputParser):\n    def parse(self, output: str) -> Any:\n        json_dict = parse_json_markdown(output)\n        try:\n            query_and_filters = VectorStoreQuerySpec.model_validate(json_dict)\n        except ValidationError as e:\n            raise OutputParserException(\n                f\"Failed to validate query spec. Error: {e}. Got JSON dict: {json_dict}\"\n            ) from e\n\n        return StructuredOutput(raw_output=output, parsed_output=query_and_filters)\n\n    def format(self, prompt_template: str) -> str:\n        return prompt_template\n","sourceCodeStart":1,"sourceCodeEnd":25,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/vector_store/retrievers/auto_retriever/output_parser.py#L1-L25","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a stronger LLM or one with structured/function-calling output, and keep the default vector store query prompt.","If you customized prompt_template_str, make it demand exactly {\"query\": str, \"filters\": [{\"key\": str, \"value\": str, \"operator\": str}]} — the VectorStoreQuerySpec schema.","Catch OutputParserException at retriever.run/retrieve call time and retry the query once or fall back to a plain VectorIndexRetriever without auto filters."],"exampleFix":"# before\nretriever = VectorIndexAutoRetriever(index, llm=weak_llm)  # weak_llm emits {\"filters\": \"category=science\"}\nnodes = retriever.retrieve(\"news about AI\")  # OutputParserException\n\n# after\nretriever = VectorIndexAutoRetriever(index, llm=strong_llm)\ntry:\n    nodes = retriever.retrieve(\"news about AI\")\nexcept OutputParserException:\n    nodes = VectorIndexRetriever(index).retrieve(\"news about AI\")  # fallback, no auto filters","handlingStrategy":"try-catch","validationCode":"from llama_index.core.output_parsers.utils import parse_json_markdown\nfrom llama_index.core.vector_stores.types import VectorStoreQuerySpec\n\ndef llm_output_is_valid_spec(raw: str) -> bool:\n    try:\n        VectorStoreQuerySpec.model_validate(parse_json_markdown(raw))\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"from llama_index.core.output_parsers.base import OutputParserException\n\ntry:\n    nodes = auto_retriever.retrieve(query_str)\nexcept OutputParserException:\n    nodes = VectorIndexRetriever(index).retrieve(query_str)  # graceful degradation, no auto filters","preventionTips":["Use an LLM with reliable JSON output (structured/function calling) for VectorIndexAutoRetriever.","If customizing prompt_template_str, keep the required {\"query\": str, \"filters\": [{\"key\",\"value\",\"operator\"}]} JSON shape.","Wrap auto-retriever calls in OutputParserException handling with a plain-retriever fallback."],"tags":["auto-retriever","llm-output-parsing","pydantic","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}