{"record":{"id":"882829db61cdd562","repo":"run-llama/llama_index","slug":"detected-nested-async-please-use-nest-asyncio-app","errorCode":null,"errorMessage":"Detected nested async. Please use nest_asyncio.apply() to allow nested event loops.Or, use async entry methods like `aquery()`, `aretriever`, `achat`, etc.","messagePattern":"Detected nested async\\. Please use nest_asyncio\\.apply\\(\\) to allow nested event loops\\.Or, use async entry methods like `aquery\\(\\)`, `aretriever`, `achat`, etc\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/async_utils.py","lineNumber":74,"sourceCode":"                asyncio.set_event_loop(new_loop)\n                try:\n                    return ctx.run(new_loop.run_until_complete, coro)\n                finally:\n                    new_loop.close()\n\n            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:\n                future = executor.submit(run_coro_in_thread)\n                return future.result()\n        else:\n            # If we're here, there's an existing loop but it's not running\n            return loop.run_until_complete(coro)\n\n    except RuntimeError as e:\n        # If we can't get the event loop, we're likely in a different thread\n        try:\n            return asyncio.run(coro)\n        except RuntimeError as e:\n            raise RuntimeError(\n                \"Detected nested async. Please use nest_asyncio.apply() to allow nested event loops.\"\n                \"Or, use async entry methods like `aquery()`, `aretriever`, `achat`, etc.\"\n            )\n\n\ndef run_async_tasks(\n    tasks: List[Coroutine],\n    show_progress: bool = False,\n    progress_bar_desc: str = \"Running async tasks\",\n) -> List[Any]:\n    \"\"\"Run a list of async tasks.\"\"\"\n    tasks_to_execute: List[Any] = tasks\n    if show_progress:\n        try:\n            import nest_asyncio\n            from tqdm.asyncio import tqdm\n\n            # jupyter notebooks already have an event loop running","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/async_utils.py#L56-L92","documentation":"async_utils runs a coroutine from sync code by checking the thread's event loop. When a running loop already exists in this thread (sync code called from inside async) AND asyncio.run also fails (loop policy/thread constraints), it concludes the call is nested async and raises. The message itself offers the two fixes: nest_asyncio.apply() or using the async entry points (aquery, aretrieve, achat, ...).","triggerScenarios":"Calling a sync wrapper such as query_engine.query(...) or retriever.retrieve(...) from inside an async function / Jupyter cell (Jupyter already runs a loop), or calling .query() inside a workflow @step; the code path funnels through run_async_tasks which cannot block on the running loop.","commonSituations":"Notebooks (IPython has an active event loop); FastAPI/asyncio handlers calling sync llama-index APIs; mixing sync examples into async codebases; calling vector store or index construction methods synchronously inside async code.","solutions":["Switch the call site to the async variant: await query_engine.aquery(...), await retriever.aretrieve(...), await llm.achat(...).","In Jupyter, run `import nest_asyncio; nest_asyncio.apply()` once at startup (nest_asyncio is already a llama-index-core dependency).","For server apps, push blocking sync calls to a thread: `await asyncio.to_thread(engine.query, q)`."],"exampleFix":"# before (inside async def or Jupyter)\nresponse = query_engine.query(\"what is this?\")  # RuntimeError\n\n# after\nresponse = await query_engine.aquery(\"what is this?\")\n\n# Jupyter alternative\nimport nest_asyncio\nnest_asyncio.apply()\nresponse = query_engine.query(\"what is this?\")","handlingStrategy":"validation","validationCode":"import asyncio\n\ndef in_running_loop() -> bool:\n    try:\n        return asyncio.get_running_loop() is not None\n    except RuntimeError:\n        return False\n\n# if in_running_loop(): call aquery/aretrieve/achat instead of sync versions","typeGuard":null,"tryCatchPattern":"try:\n    result = engine.query(q)\nexcept RuntimeError as e:\n    if \"nested async\" in str(e):\n        raise RuntimeError(\"call await engine.aquery(q) instead\") from e\n    raise","preventionTips":["Standardize on async entry points (aquery/aretrieve/achat) inside async apps and notebooks.","In Jupyter, apply nest_asyncio once at kernel start.","Run sync llama-index calls inside asyncio.to_thread when bridging into async code."],"tags":["async","event-loop","jupyter","sync-async-bridge"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}