{"record":{"id":"4e5a08497aad2197","repo":"run-llama/llama_index","slug":"this-query-engine-does-not-support-query","errorCode":null,"errorMessage":"This query engine does not support _query.","messagePattern":"This query engine does not support _query\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/query_engine/custom.py","lineNumber":74,"sourceCode":"                query_str = str_or_query_bundle\n            raw_response = await self.acustom_query(query_str)\n            return (\n                Response(raw_response)\n                if isinstance(raw_response, str)\n                else raw_response\n            )\n\n    @abstractmethod\n    def custom_query(self, query_str: str) -> STR_OR_RESPONSE_TYPE:\n        \"\"\"Run a custom query.\"\"\"\n\n    async def acustom_query(self, query_str: str) -> STR_OR_RESPONSE_TYPE:\n        \"\"\"Run a custom query asynchronously.\"\"\"\n        # by default, just run the synchronous version\n        return self.custom_query(query_str)\n\n    def _query(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:\n        raise NotImplementedError(\"This query engine does not support _query.\")\n\n    async def _aquery(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:\n        raise NotImplementedError(\"This query engine does not support _aquery.\")\n","sourceCodeStart":56,"sourceCodeEnd":78,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/custom.py#L56-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call the public string API: engine.query('your question') — this routes to your custom_query implementation.","If a framework demands the _query interface, subclass RetrieverQueryEngine (or BaseQueryEngine with a real _query) instead of CustomQueryEngine.","Verify you actually subclassed CustomQueryEngine and implemented custom_query — an isinstance mix-up (wrong engine passed in) is a frequent root cause.","Audit calling code for direct `_query(`/`_aquery(` invocations and replace them with `.query(...)`."],"exampleFix":"# before\nqb = QueryBundle(query_str=\"what is the revenue?\")\nresp = engine._query(qb)  # NotImplementedError\n\n# after\nresp = engine.query(\"what is the revenue?\")  # -> custom_query(\"what is the revenue?\")","handlingStrategy":"type-guard","validationCode":"from llama_index.core.query_engine import CustomQueryEngine\n\ndef assert_string_queryable(engine) -> None:\n    if not hasattr(engine, \"custom_query\"):\n        raise TypeError(\"engine does not implement the string-query contract\")\n\n# call sites must use engine.query(\"...\") — never engine._query(query_bundle)","typeGuard":"from llama_index.core.query_engine.custom import CustomQueryEngine\n\ndef is_string_query_engine(engine) -> bool:\n    return isinstance(engine, CustomQueryEngine) and callable(getattr(engine, \"custom_query\", None))","tryCatchPattern":null,"preventionTips":["Only call the public query(str) on CustomQueryEngine subclasses.","Never call _query/_aquery from application code — they are framework-internal contracts.","If a wrapper requires the QueryBundle path, subclass BaseQueryEngine and implement _query properly."],"tags":["llama-index","query-engine","custom-query-engine","api-misuse","not-implemented"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}