docling-project/docling · error · ServiceUnavailableError

Service transport request failed.

Error message

Service transport request failed.

What it means

In the async service client's retry loop, an httpx.HTTPError (connect failure, read timeout, TLS error) that is not eligible for further transport retries is converted into ServiceUnavailableError with the original exception chained as detail. This tells the caller the HTTP transport to the Docling service could not complete the request even after the configured retry policy, e.g. the service is down or unreachable.

Source

Thrown at docling/service_client/_async_client.py:699

                    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:
                    await asyncio.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:
                await asyncio.sleep(delay)

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

    async def _submit_convert_task(
        self,
        source: SourceType,
        options: ConvertDocumentsRequestOptions,
        target: SubmitTarget,
        async_client: httpx.AsyncClient,
        request_headers: dict[str, str] | None = None,

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Verify the service URL and that the Docling service is up (curl the health endpoint).
  2. If running locally, start the docling-serve container/process before submitting work.
  3. Increase http_retries on the client to tolerate transient outages.
  4. Check proxies, VPN, DNS, and firewall rules between client and service.

Example fix

# before
client = DocumentConverterClient(base_url='http://localhost:5001')
await client.convert_file(...)  # ServiceUnavailableError: transport failed

# after
# start service first, then point at the correct port
client = DocumentConverterClient(base_url='http://localhost:5001', http_retries=5)
async with client:
    result = await client.convert_file(...)
Defensive patterns

Strategy: retry

Validate before calling

import httpx

async def service_up(url: str) -> bool:
    try:
        async with httpx.AsyncClient() as c:
            r = await c.get(url.rstrip('/') + '/health')
            return r.status_code < 500
    except httpx.HTTPError:
        return False

Try / catch

from docling.service_client.exceptions import ServiceUnavailableError

for attempt in range(5):
    try:
        result = await client.convert_file(f)
        break
    except ServiceUnavailableError as e:
        if 'transport' not in str(e):
            raise
        await asyncio.sleep(2 ** attempt)

Prevention

When it happens

Trigger: The Docling service URL is wrong or unreachable (connection refused); the service is overloaded and connections time out; a proxy or firewall resets connections; DNS resolution failure; retries exhausted for retryable transport errors via _transport_retry_delay returning None.

Common situations: Running against a local docker service that is not started; pointing the client at a stale/internal hostname; CI environments without network access to the service endpoint; service restarting during a long batch job.

Related errors

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