docling-project/docling · error · TaskExecutionError

{last_status.error_message or f"Task {task_id} failed."}

Error message

{last_status.error_message or f"Task {task_id} failed."}

What it means

Raised as TaskExecutionError when a result lookup returned 'Task result not found', the last known status is terminal, and that status is 'failure'. The message is the error_message recorded by the service for the failed task, or the fallback 'Task {task_id} failed.' if the service stored none. The structured failure payload is attached via the 'failure' attribute (last_status.failure).

Source

Thrown at docling/service_client/client.py:672

            return None

        now = datetime.now(tz=retry_at.tzinfo or timezone.utc)
        return max(0.0, (retry_at - now).total_seconds())

    def _raise_for_result_404(
        self,
        task_id: str,
        response: httpx.Response,
        last_status: TaskStatusResponse | None,
    ) -> None:
        detail = self._http_error_detail(response)
        if detail == "Task not found.":
            raise TaskNotFoundError(f"Task {task_id} was not found.")
        if detail is not None and detail.startswith("Task result not found"):
            if last_status is not None and is_terminal_task_status(last_status):
                if last_status.task_status == "failure":
                    message = last_status.error_message or f"Task {task_id} failed."
                    raise TaskExecutionError(message, failure=last_status.failure)
                raise ResultExpiredError(f"Result for task {task_id} has expired.")
            raise ResultNotReadyError(f"Result for task {task_id} is not ready.")
        raise ServiceError(
            "Unexpected result lookup error.",
            status_code=response.status_code,
            detail=detail,
        )

    def _raise_if_task_failure_result(self, response: httpx.Response) -> None:
        content_type = response.headers.get("content-type", "")
        if "json" not in content_type.lower():
            return

        try:
            payload = response.json()
        except ValueError:
            return

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Inspect the exception's 'failure' attribute (TaskFailure) for the machine-readable cause returned by the service.
2. Fix the document-side problem it reports: decrypt/password-protect the PDF, reduce page count via page_range, or lower max_file_size, then resubmit.
3. Log task_id plus failure details so recurring document failures can be triaged in bulk.
4. For batch pipelines, catch TaskExecutionError per item and continue rather than aborting the whole batch.

Example fix

# before
result = job.result()  # raises TaskExecutionError with server message

# after
from docling.service_client.exceptions import TaskExecutionError

try:
    result = job.result()
except TaskExecutionError as exc:
    print("task failed:", exc.failure)  # structured failure payload
    result = None

# before fetching result, check status is terminal-success
status = client._poll_task_status(task_id, wait=0)  # or public status API
if status.task_status == "failure":
    handle_failure(status.error_message, status.failure)

from docling.service_client.exceptions import TaskExecutionError

try:
    result = job.result()
except TaskExecutionError as exc:
    failure = exc.failure  # structured TaskFailure or None
    log.error("task failed: %s", failure or exc)
    mark_document_failed(source, str(exc))

When it happens

Trigger: Polling or fetching the result of a task whose last observed TaskStatusResponse has task_status == 'failure' and whose result artifact is gone (404 'Task result not found'); the conversion itself failed server-side (e.g. unsupported/corrupt input, pipeline crash, limits exceeded).

Common situations: Fetching results long after submission so failed-task artifacts were cleaned up, batch jobs where failures are only surfaced at result-collection time, or conversions that failed due to document-specific problems (encrypted PDF, OOM on huge files).

Related errors

• {task_failure.failure.message}
• Task {task_id} was not found.
• Timed out waiting for task {task_id} after {timeout:.2f}s.
• Result for task {task_id} has expired.
• Result for task {task_id} is not ready.

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/64a97d1ac012d912. Report an issue: GitHub.