docling-project/docling · error · TaskExecutionError

{task_failure.failure.message}

Error message

{task_failure.failure.message}

What it means

Raised as TaskExecutionError from _raise_if_task_failure_result when a (JSON) response body carries kind == 'TaskFailureResult'. The message is task_failure.failure.message — the structured failure the service embedded in the response — and the full TaskFailure is attached via the 'failure' kwarg. This path surfaces server-side conversion failures delivered in-band with a response rather than through the status endpoint.

Source

Thrown at docling/service_client/client.py:695

            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

        if not isinstance(payload, dict) or payload.get("kind") != "TaskFailureResult":
            return

        task_failure = TaskFailureResult.model_validate(payload)
        raise TaskExecutionError(
            task_failure.failure.message,
            failure=task_failure.failure,
        )

    def _raise_for_generic_http_error(
        self,
        response: httpx.Response,
        message: str,
    ) -> None:
        if response.status_code == 402:
            usage_limit = self._parse_usage_limit_exceeded_response(response)
            raise UsageLimitExceededError(
                message,
                status_code=response.status_code,
                detail=None if usage_limit is None else usage_limit.message,
                current_usage=(
                    None if usage_limit is None else usage_limit.details.currentUsage
                ),

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Read exc.failure for the structured cause (message, code, details) and address the underlying document/pipeline issue.
2. Re-submit after fixing the input (valid PDF/Office file, correct source descriptor, within limits).
3. Upgrade docling and docling-serve to matching versions if the failure kind suggests a protocol mismatch.
4. Log the failure payload with the task_id for server-side correlation in service logs.

Example fix

# before
result = job.result()  # TaskExecutionError from in-band TaskFailureResult

# after
from docling.service_client.exceptions import TaskExecutionError

try:
    result = job.result()
except TaskExecutionError as exc:
    if exc.failure is not None:
        log.warning("failure code=%s msg=%s", exc.failure.code, exc.failure.message)
    raise

from docling.service_client.exceptions import TaskExecutionError

try:
    result = job.result()
except TaskExecutionError as exc:
    if exc.failure is not None:
        record_failure(exc.failure)  # structured payload
    raise

When it happens

Trigger: Any response-handling code path that calls _raise_if_task_failure_result (result/status fetches) receiving a JSON body whose payload is a TaskFailureResult envelope; the body parses as JSON, is a dict, and payload['kind'] == 'TaskFailureResult'.

Common situations: The service reports conversion failure asynchronously via the response body (e.g. async job result endpoint returning the failure object), invalid or unsupported source documents, or server pipeline exceptions serialized as TaskFailureResult.

Related errors

• {last_status.error_message or f"Task {task_id} failed."}
• 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/95f824777afde2a7. Report an issue: GitHub.