docling-project/docling · error · ArtifactDownloadError

Artifact download failed: {exc}

Error message

Artifact download failed: {exc}

What it means

Raised as ArtifactDownloadError wrapping any httpx.HTTPError raised by the synchronous artifact download: connection failures, DNS errors, TLS problems, or read timeouts (bounded by artifact_download_timeout, default 60s). The original exception is chained via 'from exc' so the cause is inspectable.

Source

Thrown at docling/service_client/client.py:1914

                            url = self._next_redirect_url(url, response)
                            continue
                        if response.status_code != 200:
                            raise ArtifactDownloadError(
                                "Artifact download failed with HTTP "
                                f"{response.status_code}."
                            )
                        chunks: list[bytes] = []
                        total = 0
                        for chunk in response.iter_bytes():
                            total += len(chunk)
                            self._check_artifact_size(total)
                            chunks.append(chunk)
                        return b"".join(chunks)
                raise ArtifactDownloadError(
                    "Too many redirects while downloading artifact."
                )
        except httpx.HTTPError as exc:
            raise ArtifactDownloadError(f"Artifact download failed: {exc}") from exc

    async def _download_artifact_bytes_async(self, uri: str) -> bytes:
        timeout = httpx.Timeout(self._artifact_download_timeout)
        try:
            async with httpx.AsyncClient(
                timeout=timeout, follow_redirects=False
            ) as client:
                url = uri
                for _ in range(MAX_ARTIFACT_DOWNLOAD_REDIRECTS + 1):
                    self._validate_artifact_url(url)
                    async with client.stream("GET", url) as response:
                        if response.is_redirect:
                            url = self._next_redirect_url(url, response)
                            continue
                        if response.status_code != 200:
                            raise ArtifactDownloadError(
                                "Artifact download failed with HTTP "
                                f"{response.status_code}."

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Increase artifact_download_timeout in the client constructor if artifacts are large or the link is slow
2. Verify connectivity: curl the presigned URL from the same machine/container
3. Configure proxy environment variables (HTTPS_PROXY) or trust the internal CA if TLS fails

Example fix

// before
client = DoclingServiceClient(url, artifact_download_timeout=60.0)

// after
client = DoclingServiceClient(url, artifact_download_timeout=300.0)

import socket
from urllib.parse import urlparse
host = urlparse(artifact_url).hostname
assert host and socket.gethostbyname(host), 'artifact host unresolvable'

def is_artifact_download_error(exc: BaseException) -> bool:
    return isinstance(exc, ArtifactDownloadError)

try:
    results = list(client.convert_all(sources))
except ArtifactDownloadError as exc:
    if 'timeout' in str(exc).lower() or 'connect' in str(exc).lower():
        time.sleep(5)
        retry_with_backoff()

When it happens

Trigger: Artifact host unreachable, DNS resolution failure, TLS certificate error, or a slow object store exceeding artifact_download_timeout during convert() materialization.

Common situations: Corporate proxies blocking the object-store domain; ephemeral DNS failures in containers; large artifacts on slow links hitting the 60s default; self-signed certificates on internal MinIO deployments.

Related errors

• gRPC infer call failed for model {self.model_name}: {exc}
• Artifact download failed with HTTP {response.status_code}.
• Too many redirects while downloading artifact.
• Refusing to download artifact from a non-public URL: {url}.
• Artifact download redirect is missing a Location header.

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