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.

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 request failed after retry loop.
• Service request failed after retry loop.
• Service transport request failed.
• Service transport request failed after retries.
• {error_message}

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

Appendix: 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)