{"record":{"id":"359b733dcecb790f","repo":"run-llama/llama_index","slug":"this-query-engine-does-not-support-aquery","errorCode":null,"errorMessage":"This query engine does not support _aquery.","messagePattern":"This query engine does not support _aquery\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/query_engine/custom.py","lineNumber":77,"sourceCode":"                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":59,"sourceCodeEnd":78,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/custom.py#L59-L78","documentation":"The async twin of the previous stub: CustomQueryEngine._aquery(query_bundle) raises NotImplementedError because the class supports only the string-based async surface, acustom_query() (defaulted to run the sync custom_query). Hitting it means something drove the engine through the QueryBundle-based async path that CustomQueryEngine intentionally does not implement.","triggerScenarios":"Awaiting engine._aquery(query_bundle) directly, or plugging a CustomQueryEngine into async orchestration (agents, pipelines, routers) that awaits the protected _aquery API rather than calling the overridden aquery(str). engine.aquery('question') is fine — it dispatches to custom_query.","commonSituations":"Async agent frameworks or benchmark harnesses that standardize on BaseQueryEngine internals; refactors that swapped a RetrieverQueryEngine for a CustomQueryEngine without changing call sites; tests calling protected methods to 'skip boilerplate'.","solutions":["Use the public async API: await engine.aquery('your question') — it calls custom_query under the hood.","If the _aquery contract is required, base your class on BaseQueryEngine/RetrieverQueryEngine and implement _aquery yourself.","Override acustom_query() if your custom logic is genuinely async, instead of trying to make _aquery work.","Search the codebase for `_aquery(` and route those call sites through aquery()."],"exampleFix":"# before\nresp = await engine._aquery(QueryBundle(query_str=\"summary?\"))  # NotImplementedError\n\n# after\nresp = await engine.aquery(\"summary?\")  # -> acustom_query -> custom_query","handlingStrategy":"type-guard","validationCode":"from llama_index.core.query_engine.custom import CustomQueryEngine\n\ndef assert_aqueryable(engine) -> None:\n    if isinstance(engine, CustomQueryEngine) and not hasattr(engine, \"_aquery_impl\"):\n        # fine: aquery(str) routes to acustom_query; just never call _aquery directly\n        pass\n\ndef run_query(engine, q: str):\n    return engine.aquery(q) if hasattr(engine, \"aquery\") else engine.query(q)","typeGuard":"from llama_index.core.query_engine.custom import CustomQueryEngine\n\ndef supports_string_aquery(engine) -> bool:\n    return isinstance(engine, CustomQueryEngine) and callable(getattr(engine, \"acustom_query\", None))","tryCatchPattern":null,"preventionTips":["Use await engine.aquery(\"question\") for async custom engines.","Implement acustom_query() for genuinely async logic instead of touching _aquery.","Grep async orchestration code for `_aquery(` calls and route them through aquery()."],"tags":["llama-index","query-engine","async","custom-query-engine","api-misuse"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}