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

TextToCypherRetriever generates Cypher from natural language and runs it via graph_store.structured_query, so it validates graph_store.supports_structured_queries at __init__ and refuses stores that cannot run Cypher (e.g. the default SimplePropertyGraphStore).

Source

Thrown at llama-index-core/llama_index/core/indices/property_graph/sub_retrievers/text_to_cypher.py:81

            The template to use for summarizing the response. Defaults to None.

    """

    def __init__(
        self,
        graph_store: PropertyGraphStore,
        llm: Optional[LLM] = None,
        text_to_cypher_template: Optional[Union[PromptTemplate, str]] = None,
        response_template: Optional[str] = None,
        cypher_validator: Optional[Callable] = None,
        allowed_output_fields: Optional[List[str]] = None,
        include_raw_response_as_metadata: Optional[bool] = False,
        summarize_response: Optional[bool] = False,
        summarization_template: Optional[Union[PromptTemplate, str]] = 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

        if isinstance(text_to_cypher_template, str):
            text_to_cypher_template = PromptTemplate(text_to_cypher_template)

        if isinstance(summarization_template, str):
            summarization_template = PromptTemplate(summarization_template)

        self.response_template = response_template or DEFAULT_RESPONSE_TEMPLATE
        self.text_to_cypher_template = (
            text_to_cypher_template or graph_store.text_to_cypher_template
        )
        self.cypher_validator = cypher_validator
        self.allowed_output_fields = allowed_output_fields
        self.include_raw_response_as_metadata = include_raw_response_as_metadata

View on GitHub (pinned to afd0fef371)

Solutions

1. Attach a structured-query-capable store: Neo4jPropertyGraphStore, NeptunePropertyGraphStore, or KuzuPropertyGraphStore
2. Set sub_retrievers=['vector', 'synonym'] (no 'text_to_cypher') when using in-memory stores
3. For custom stores, set supports_structured_queries = True and implement structured_query()

Example fix

# before
index = PropertyGraphIndex.from_documents(docs)  # default in-memory store
retriever = TextToCypherRetriever(index=index)  # raises

# after
from llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore
index = PropertyGraphIndex.from_documents(
    docs, property_graph_store=Neo4jPropertyGraphStore(username=..., password=..., url=...)
)

if index.property_graph_store.supports_structured_queries:
    sub_retrievers = ['text_to_cypher', 'vector', 'synonym']
else:
    sub_retrievers = ['vector', 'synonym']
retriever = index.as_retriever(sub_retrievers=sub_retrievers)

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

try:
    retriever = TextToCypherRetriever(index=index)
except ValueError as e:
    if 'cypher' in str(e):
        retriever = index.as_retriever(sub_retrievers=['vector', 'synonym'])
    else:
        raise

When it happens

Trigger: Building PropertyGraphIndex with an in-memory/simple store (or omitting the store so the default is used) and then constructing TextToCypherRetriever(index=...) or including it in PGRetriever's sub_retrievers=['text_to_cypher'].

Common situations: Running examples/tutorials that assume Neo4j while locally using the default store; enabling the default 'text_to_cypher' sub-retriever on an index backed by SimplePropertyGraphStore.

Related errors

• The provided graph store does not support cypher queries.
• Vector query not implemented for SimplePropertyGraphStore.
• Client not implemented for SimplePropertyGraphStore.
• Ref doc info not implemented for PropertyGraphIndex. All ins
• Invalid return type. All items in the list must be of the sa

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