{"record":{"id":"35ca988f85e909c4","repo":"run-llama/llama_index","slug":"the-provided-graph-store-does-not-support-cypher-q","errorCode":null,"errorMessage":"The provided graph store does not support cypher queries.","messagePattern":"The provided graph store does not support cypher queries\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/property_graph/sub_retrievers/cypher_template.py","lineNumber":38,"sourceCode":"            The output class to use for the LLM.\n            Should contain the params needed for the cypher query.\n        cypher_query (str):\n            The cypher query to use, with templated params.\n        llm (Optional[LLM], optional):\n            The language model to use. Defaults to Settings.llm.\n\n    \"\"\"\n\n    def __init__(\n        self,\n        graph_store: PropertyGraphStore,\n        output_cls: Type[BaseModel],\n        cypher_query: str,\n        llm: Optional[LLM] = None,\n        **kwargs: Any,\n    ) -> None:\n        if not graph_store.supports_structured_queries:\n            raise ValueError(\n                \"The provided graph store does not support cypher queries.\"\n            )\n\n        self.llm = llm or Settings.llm\n        # Explicit type hint to suppress:\n        #   `Expected type '_SpecialForm[BaseModel]', got 'Type[BaseModel]' instead`\n        self.output_cls: Type[BaseModel] = output_cls\n        self.cypher_query = cypher_query\n\n        super().__init__(\n            graph_store=graph_store, include_text=False, include_properties=False\n        )\n\n    def retrieve_from_graph(self, query_bundle: QueryBundle) -> List[NodeWithScore]:\n        question = query_bundle.query_str\n\n        response = self.llm.structured_predict(\n            self.output_cls, PromptTemplate(question)","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/property_graph/sub_retrievers/cypher_template.py#L20-L56","documentation":"CypherTemplateRetriever executes a fixed parameterized Cypher query against the graph store, so it requires graph_store.supports_structured_queries to be True. In-memory stores like SimplePropertyGraphStore do not implement structured query execution and are rejected at construction time.","triggerScenarios":"Instantiating CypherTemplateRetriever(graph_store=SimplePropertyGraphStore(), output_cls=..., cypher_query=...) — or any custom PropertyGraphStore whose supports_structured_queries property returns False.","commonSituations":"Prototyping with the default in-memory property graph store (property_store=SimplePropertyGraphStore) and then swapping in a cypher-based retriever; writing a custom graph store and forgetting to declare supports_structured_queries = True plus structured_query().","solutions":["Use a Cypher-capable store such as Neo4jPropertyGraphStore or KuzuPropertyGraphStore (pip install llama-index-graph-stores-neo4j)","If using a custom store, implement supports_structured_queries = True and structured_query()/astructured_query()","Check graph_store.supports_structured_queries before building the retriever and fall back to a vector/context retriever"],"exampleFix":"# before\nfrom llama_index.core.graph_stores import SimplePropertyGraphStore\nretriever = CypherTemplateRetriever(graph_store=SimplePropertyGraphStore(), ...)\n\n# after\nfrom llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore\nretriever = CypherTemplateRetriever(graph_store=Neo4jPropertyGraphStore(...), ...)","handlingStrategy":"validation","validationCode":"if not graph_store.supports_structured_queries:\n    raise ValueError(\n        f'{type(graph_store).__name__} cannot run cypher; use Neo4j/Kuzu or pick a non-cypher retriever'\n    )\nretriever = CypherTemplateRetriever(graph_store=graph_store, ...)","typeGuard":"def supports_cypher(store) -> bool:\n    return bool(getattr(store, 'supports_structured_queries', False))","tryCatchPattern":"try:\n    retriever = CypherTemplateRetriever(graph_store=store, ...)\nexcept ValueError as e:\n    if 'cypher' in str(e):\n        retriever = VectorContextRetriever(graph_store=store)  # fallback retriever\n    else:\n        raise","preventionTips":["Check store.supports_structured_queries before choosing retrievers","Keep a capability map of which integrations support cypher/vector/synonym queries in your app config"],"tags":["llama-index","property-graph","cypher","graph-store","capability-check"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}