{"record":{"id":"3488f1bf70b6d016","repo":"cocoindex-io/cocoindex","slug":"cocoindex-timeout-deadline-exceeded","errorCode":null,"errorMessage":"CocoIndex timeout deadline exceeded","messagePattern":"CocoIndex timeout deadline exceeded","errorType":"exception","errorClass":"DeadlineExceededError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/_internal/api.py","lineNumber":624,"sourceCode":"            if isinstance(items, AsyncIterable):\n                async for item in items:\n                    _schedule_one(item)\n            else:\n                for item in items:\n                    _schedule_one(item)\n        except Exception as exc:\n            schedule_error = exc\n\n    results = [task.result() for task in tasks]\n\n    if schedule_error is not None:\n        raise schedule_error\n\n    for outcome in results:\n        if not isinstance(outcome, _MapTaskFailure):\n            continue\n        if isinstance(outcome.error, DeadlineExceededError):\n            raise DeadlineExceededError(\n                \"CocoIndex timeout deadline exceeded\"\n            ) from outcome.error\n        raise outcome.error\n    # All started tasks completed successfully; check the caller's deadline\n    # before returning their values.\n    check_cancellation()\n    return [cast(_MapTaskSuccess[ReturnT], outcome).value for outcome in results]\n\n\n_MOUNT_TARGET_SYMBOL = Symbol(\"cocoindex/mount_target\")\n\n\nasync def mount_target(\n    target_state: TargetState[TargetHandler[_ValueT, Any, _ChildHandlerT]],\n) -> TargetStateProvider[_ValueT, _ChildHandlerT]:\n    \"\"\"\n    Mount a target, ensuring its container target state is applied before returning\n    the child TargetStateProvider.","sourceCodeStart":606,"sourceCodeEnd":642,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/_internal/api.py#L606-L642","documentation":"map() fans out tasks with a deadline. When a spawned task fails because the deadline elapsed (DeadlineExceededError), map() re-raises it as 'CocoIndex timeout deadline exceeded'. It signals that the parallel work did not finish within the allowed time budget.","triggerScenarios":"Calling coco.map() (directly or via await) with a deadline/check_cancellation budget that the mapped tasks exceed — e.g. very slow per-item work, too many items, or a too-tight timeout.","commonSituations":"Large fan-outs over slow I/O; embedding/model-inference calls exceeding the configured timeout; reduced time budget after tuning; hanging downstream services.","solutions":["Increase the deadline/timeout budget for the map() call or surrounding operation","Speed up or batch the per-item work (e.g. smaller batches, caching, parallelism tuning)","Catch DeadlineExceededError and implement chunked processing with checkpoints for very large item sets","Investigate slow downstream dependencies (DB, network, model servers) causing tasks to stall"],"exampleFix":"// before\nresults = await coco.map(process_item, items)  # blows the deadline on 100k items\n// after\nfor chunk in chunks(items, 10_000):\n    results = await coco.map(process_item, chunk)","handlingStrategy":"try-catch","validationCode":"import time\nbudget = deadline - time.monotonic()\nif budget < expected_per_item_cost * len(items):\n    items = items[: max(1, int(budget // expected_per_item_cost))]","typeGuard":null,"tryCatchPattern":"try:\n    results = await coco.map(fn, items)\nexcept DeadlineExceededError:\n    results = []\n    for chunk in chunks(items, BATCH):\n        results.extend(await coco.map(fn, chunk))","preventionTips":["Budget the deadline against item count and per-item latency before fanning out","Chunk very large item sets instead of one huge map()","Monitor downstream dependency latency; slow callees are the usual cause"],"tags":["timeout","concurrency","deadline"],"backgroundTag":"request-timeout","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}