{"record":{"id":"694d21fd6fb2645f","repo":"docling-project/docling","slug":"timed-out-waiting-for-task-task-id-after-timeou","errorCode":null,"errorMessage":"Timed out waiting for task {task_id} after {timeout:.2f}s.","messagePattern":"Timed out waiting for task (.+?) after (.+?)s\\.","errorType":"exception","errorClass":"TaskTimeoutError","httpStatus":null,"severity":"error","filePath":"docling/service_client/_async_client.py","lineNumber":893,"sourceCode":"        if response.status_code == 404:\n            raise TaskNotFoundError(f\"Task {task_id} was not found.\")\n        if response.status_code != 200:\n            self._raise_for_generic_http_error(\n                response, f\"Polling task {task_id} failed.\"\n            )\n        return TaskStatusResponse.model_validate_json(response.text)\n\n    async def _wait_for_terminal_status(\n        self,\n        task_id: str,\n        timeout: float,\n        async_client: httpx.AsyncClient,\n    ) -> TaskStatusResponse:\n        deadline = time.monotonic() + timeout\n        while True:\n            remaining = deadline - time.monotonic()\n            if remaining <= 0:\n                raise TaskTimeoutError(\n                    f\"Timed out waiting for task {task_id} after {timeout:.2f}s.\"\n                )\n            wait = min(self._poll_server_wait, remaining)\n            logger.info(\"Polling status for task_id=%s wait=%.2fs\", task_id, wait)\n            poll_started = time.monotonic()\n            update = await self._poll_task_status_using_client(\n                task_id=task_id,\n                wait=wait,\n                async_client=async_client,\n            )\n            logger.info(\n                \"Received status for task_id=%s status=%s position=%s\",\n                task_id,\n                update.task_status,\n                update.task_position,\n            )\n            if is_terminal_task_status(update):\n                return update","sourceCodeStart":875,"sourceCodeEnd":911,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/_async_client.py#L875-L911","documentation":"_wait_for_terminal_status polls the task with long-poll waits until a monotonic deadline. When the deadline (submission time + timeout) passes before the task reaches a terminal status, TaskTimeoutError is raised, reporting the task id and the configured timeout. The task may still be running server-side; only the client gave up waiting.","triggerScenarios":"Large documents or busy service making conversion exceed the configured timeout; timeout set too small for queued tasks (position in queue high); GPU-less service processing many pages slowly; deadlock/overload on the service so the task never completes.","commonSituations":"Default timeouts with 500+ page PDFs; batch submissions saturating the service; cold model load on first request taking minutes; network latency inflating each long-poll round trip.","solutions":["Increase the timeout passed to the wait/conversion call.","Reduce service load or scale docling-serve (more workers/GPUs) so tasks finish faster.","Split very large documents into smaller conversion requests.","Catch TaskTimeoutError and poll again later — the task may still complete and can be retrieved by id."],"exampleFix":"# before\nresult = await client.convert_and_get(f, timeout=60.0)  # TaskTimeoutError on big file\n\n# after\nfrom docling.service_client.exceptions import TaskTimeoutError\ntry:\n    result = await client.convert_and_get(f, timeout=900.0)\nexcept TaskTimeoutError:\n    await asyncio.sleep(300)\n    result = await client.get_task_result(task_id)  # pick up later","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"from docling.service_client.exceptions import TaskTimeoutError\n\ntry:\n    result = await client.convert_and_get(f, timeout=900.0)\nexcept TaskTimeoutError:\n    await asyncio.sleep(300)\n    result = await client.get_task_result(task_id)  # task may be done by now","preventionTips":["Scale timeout with document size (pages, images).","Split very large documents into smaller requests.","Monitor queue depth and scale the service for batch workloads."],"tags":["service-client","timeout","polling","task"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}