run-llama/llama_index · error · NotImplementedError

This query engine does not support _query.

Error message

This query engine does not support _query.

What it means

CustomQueryEngine implements the LLM-agnostic query surface via custom_query(query_str: str) and deliberately stubs the retriever-oriented _query(query_bundle) with NotImplementedError. This error means the engine was driven through the QueryBundle/_query path — which CustomQueryEngine explicitly does not support — instead of the string-based query()/custom_query() path.

Source

Thrown at llama-index-core/llama_index/core/query_engine/custom.py:74

                query_str = str_or_query_bundle
            raw_response = await self.acustom_query(query_str)
            return (
                Response(raw_response)
                if isinstance(raw_response, str)
                else raw_response
            )

    @abstractmethod
    def custom_query(self, query_str: str) -> STR_OR_RESPONSE_TYPE:
        """Run a custom query."""

    async def acustom_query(self, query_str: str) -> STR_OR_RESPONSE_TYPE:
        """Run a custom query asynchronously."""
        # by default, just run the synchronous version
        return self.custom_query(query_str)

    def _query(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:
        raise NotImplementedError("This query engine does not support _query.")

    async def _aquery(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:
        raise NotImplementedError("This query engine does not support _aquery.")

View on GitHub (pinned to afd0fef371)

Solutions

1. Call the public string API: engine.query('your question') — this routes to your custom_query implementation.
2. If a framework demands the _query interface, subclass RetrieverQueryEngine (or BaseQueryEngine with a real _query) instead of CustomQueryEngine.
3. Verify you actually subclassed CustomQueryEngine and implemented custom_query — an isinstance mix-up (wrong engine passed in) is a frequent root cause.
4. Audit calling code for direct `_query(`/`_aquery(` invocations and replace them with `.query(...)`.

Example fix

# before
qb = QueryBundle(query_str="what is the revenue?")
resp = engine._query(qb)  # NotImplementedError

# after
resp = engine.query("what is the revenue?")  # -> custom_query("what is the revenue?")

from llama_index.core.query_engine import CustomQueryEngine

def assert_string_queryable(engine) -> None:
    if not hasattr(engine, "custom_query"):
        raise TypeError("engine does not implement the string-query contract")

# call sites must use engine.query("...") — never engine._query(query_bundle)

from llama_index.core.query_engine.custom import CustomQueryEngine

def is_string_query_engine(engine) -> bool:
    return isinstance(engine, CustomQueryEngine) and callable(getattr(engine, "custom_query", None))

When it happens

Trigger: Calling engine._query(query_bundle) directly, or handing a CustomQueryEngine to infrastructure that invokes the _query/_aquery abstract path (e.g. using it where a retriever-backed PydanticQueryEngine is expected, some agent/routing code, or wrappers that call the protected API). Normal engine.query('some string') never reaches this branch because CustomQueryEngine overrides query() to call custom_query.

Common situations: Passing a CustomQueryEngine into a component that assumes RetrieverQueryEngine semantics; subclasses that override query() but forget to keep the string contract; test harnesses calling protected methods; copying internal call patterns from other engines.

Related errors

• This query engine does not support _aquery.
• This query engine does not support retrieve, use query direc
• code_execute_fn must be provided for CodeActAgent
• This query engine does not support retrieve, use query direc
• This query engine does not support synthesize, use query dir

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