docling-project/docling · error · ServiceUnavailableError

Service transport request failed.

Error message

Service transport request failed.

What it means

ServiceUnavailableError raised when an HTTP request to docling-serve fails at the transport level (httpx.HTTPError) and the retry policy decides not to retry — non-idempotent methods (POST uploads) get no transport retry, or the retry delay budget is exhausted. The original exception is chained and str(exc) is put in detail.

Source

Thrown at docling/service_client/client.py:2277

                    method=method_name,
                    url=url,
                    json=json,
                    data=data,
                    files=files,
                    params=params,
                    headers=headers,
                )
            except httpx.HTTPError as exc:
                delay = self._transport_retry_delay(
                    method=method_name,
                    exc=exc,
                    attempt=attempt,
                    max_retries=max_retries,
                )
                if delay is not None:
                    time.sleep(delay)
                    continue
                raise ServiceUnavailableError(
                    "Service transport request failed.",
                    detail=str(exc),
                ) from exc
            result, delay = self._check_retry(response, attempt, max_retries)
            if result is not None:
                return result
            if delay > 0:
                time.sleep(delay)

        raise ServiceUnavailableError("Service request failed after retry loop.")

    def _failure_message(self, result: ConversionResult) -> str:
        if result.errors:
            messages = "; ".join(item.error_message for item in result.errors)
            return (
                f"Conversion failed for {result.input.file} with status "
                f"{result.status.value}. Errors: {messages}"
            )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check service reachability (curl the /health endpoint) and the URL passed to the client
2. For transient outages, retry the operation at the application level — POSTs are not auto-retried to avoid duplicate submissions
3. Fix TLS/proxy configuration if the chained exception indicates certificate or connection failures

import httpx
with httpx.Client(timeout=5) as probe:
    r = probe.get(f'{service_url}/health')
    r.raise_for_status()  # fail fast before submitting work

def is_service_unavailable(exc: BaseException) -> bool:
    return isinstance(exc, ServiceUnavailableError)

try:
    task = client.submit(source)
except ServiceUnavailableError as exc:
    if exc.detail and 'connect' in exc.detail.lower():
        backoff_and_resubmit()

When it happens

Trigger: POST-based submit calls (not in TRANSPORT_RETRYABLE_HTTP_METHODS = GET/HEAD/OPTIONS) hitting a connection error, DNS failure, or TLS problem on the first attempt.

Common situations: Service pod restarting mid-request; wrong URL scheme/host; TLS cert issues; flaky links combined with non-retryable POST semantics.

Related errors

• Service transport request failed.
• Service request failed after retry loop.
• Service transport request failed after retries.
• Service request failed after retry loop.
• {error_message}

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