cocoindex-io/cocoindex · error · DeadlineExceededError

CocoIndex timeout deadline exceeded

Error message

CocoIndex timeout deadline exceeded

What it means

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.

Source

Thrown at python/cocoindex/_internal/api.py:624

            if isinstance(items, AsyncIterable):
                async for item in items:
                    _schedule_one(item)
            else:
                for item in items:
                    _schedule_one(item)
        except Exception as exc:
            schedule_error = exc

    results = [task.result() for task in tasks]

    if schedule_error is not None:
        raise schedule_error

    for outcome in results:
        if not isinstance(outcome, _MapTaskFailure):
            continue
        if isinstance(outcome.error, DeadlineExceededError):
            raise DeadlineExceededError(
                "CocoIndex timeout deadline exceeded"
            ) from outcome.error
        raise outcome.error
    # All started tasks completed successfully; check the caller's deadline
    # before returning their values.
    check_cancellation()
    return [cast(_MapTaskSuccess[ReturnT], outcome).value for outcome in results]


_MOUNT_TARGET_SYMBOL = Symbol("cocoindex/mount_target")


async def mount_target(
    target_state: TargetState[TargetHandler[_ValueT, Any, _ChildHandlerT]],
) -> TargetStateProvider[_ValueT, _ChildHandlerT]:
    """
    Mount a target, ensuring its container target state is applied before returning
    the child TargetStateProvider.

View on GitHub (pinned to e84aa99b32)

Solutions

1. Increase the deadline/timeout budget for the map() call or surrounding operation
2. Speed up or batch the per-item work (e.g. smaller batches, caching, parallelism tuning)
3. Catch DeadlineExceededError and implement chunked processing with checkpoints for very large item sets
4. Investigate slow downstream dependencies (DB, network, model servers) causing tasks to stall

Example fix

// before
results = await coco.map(process_item, items)  # blows the deadline on 100k items
// after
for chunk in chunks(items, 10_000):
    results = await coco.map(process_item, chunk)

import time
budget = deadline - time.monotonic()
if budget < expected_per_item_cost * len(items):
    items = items[: max(1, int(budget // expected_per_item_cost))]

try:
    results = await coco.map(fn, items)
except DeadlineExceededError:
    results = []
    for chunk in chunks(items, BATCH):
        results.extend(await coco.map(fn, chunk))

When it happens

Trigger: 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.

Common situations: Large fan-outs over slow I/O; embedding/model-inference calls exceeding the configured timeout; reduced time budget after tuning; hanging downstream services.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• CocoIndex timeout deadline exceeded
• timeout() requires a datetime.timedelta
• retry_transient requires a positive timeout
• {self._label} supports a single active watch() at a time.
• async_to_sync_iter must not be called from a running event l

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/3488f1bf70b6d016. Report an issue: GitHub.