docling-project/docling · error · ServiceUnavailableError

Service request failed after retry loop.

Error message

Service request failed after retry loop.

What it means

ServiceUnavailableError raised after the HTTP retry loop completes all attempts without obtaining an accepted response — retryable 5xx statuses persisted through every iteration of _check_retry. This is the 'service kept failing' terminal state, as opposed to error 393 which is a single un-retried transport failure.

Source

Thrown at docling/service_client/client.py:2287

                    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}"
            )
        return f"Conversion failed for {result.input.file} with status {result.status.value}."

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check docling-serve health and logs — sustained 5xx is a server-side problem
2. Scale the service or back off and retry later from the application
3. Tune max_retries/backoff parameters if the client exposes them for transient overload windows

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

try:
    result = client.convert(source)
except ServiceUnavailableError as exc:
    if 'after retry loop' in str(exc):
        wait_for_service_recovery_then_retry()

When it happens

Trigger: docling-serve returning 502/503/504 (or other retryable statuses) on every attempt within the retry budget — e.g. all replicas down, upstream overload, or a crash-looping deployment.

Common situations: Service under heavy load or restarting after an upgrade; dependency (redis/db) of the service down causing sustained 5xx.

Related errors

• {error_message}
• Service transport request failed.
• Service transport request failed.
• Service request failed after retry loop.
• Service returned HTTP {response.status_code} after retries.

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