run-llama/llama_index · error · ValueError

The provided graph store does not support cypher queries.

Error message

The provided graph store does not support cypher queries.

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/indices/property_graph/sub_retrievers/cypher_template.py:38

            The output class to use for the LLM.
            Should contain the params needed for the cypher query.
        cypher_query (str):
            The cypher query to use, with templated params.
        llm (Optional[LLM], optional):
            The language model to use. Defaults to Settings.llm.

    """

    def __init__(
        self,
        graph_store: PropertyGraphStore,
        output_cls: Type[BaseModel],
        cypher_query: str,
        llm: Optional[LLM] = None,
        **kwargs: Any,
    ) -> None:
        if not graph_store.supports_structured_queries:
            raise ValueError(
                "The provided graph store does not support cypher queries."
            )

        self.llm = llm or Settings.llm
        # Explicit type hint to suppress:
        #   `Expected type '_SpecialForm[BaseModel]', got 'Type[BaseModel]' instead`
        self.output_cls: Type[BaseModel] = output_cls
        self.cypher_query = cypher_query

        super().__init__(
            graph_store=graph_store, include_text=False, include_properties=False
        )

    def retrieve_from_graph(self, query_bundle: QueryBundle) -> List[NodeWithScore]:
        question = query_bundle.query_str

        response = self.llm.structured_predict(
            self.output_cls, PromptTemplate(question)

View on GitHub (pinned to afd0fef371)

Solutions

  1. Use a Cypher-capable store such as Neo4jPropertyGraphStore or KuzuPropertyGraphStore (pip install llama-index-graph-stores-neo4j)
  2. If using a custom store, implement supports_structured_queries = True and structured_query()/astructured_query()
  3. Check graph_store.supports_structured_queries before building the retriever and fall back to a vector/context retriever

Example fix

# before
from llama_index.core.graph_stores import SimplePropertyGraphStore
retriever = CypherTemplateRetriever(graph_store=SimplePropertyGraphStore(), ...)

# after
from llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore
retriever = CypherTemplateRetriever(graph_store=Neo4jPropertyGraphStore(...), ...)
Defensive patterns

Strategy: validation

Validate before calling

if not graph_store.supports_structured_queries:
    raise ValueError(
        f'{type(graph_store).__name__} cannot run cypher; use Neo4j/Kuzu or pick a non-cypher retriever'
    )
retriever = CypherTemplateRetriever(graph_store=graph_store, ...)

Type guard

def supports_cypher(store) -> bool:
    return bool(getattr(store, 'supports_structured_queries', False))

Try / catch

try:
    retriever = CypherTemplateRetriever(graph_store=store, ...)
except ValueError as e:
    if 'cypher' in str(e):
        retriever = VectorContextRetriever(graph_store=store)  # fallback retriever
    else:
        raise

Prevention

When it happens

Trigger: Instantiating CypherTemplateRetriever(graph_store=SimplePropertyGraphStore(), output_cls=..., cypher_query=...) — or any custom PropertyGraphStore whose supports_structured_queries property returns False.

Common situations: 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().

Related errors

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