docling-project/docling · error · ArtifactDownloadError

Artifact exceeds max_artifact_download_bytes ({self._max_art

Error message

Artifact exceeds max_artifact_download_bytes ({self._max_artifact_download_bytes} bytes).

What it means

Raised as ArtifactDownloadError by _check_artifact_size when the running byte total of a streamed artifact exceeds max_artifact_download_bytes (default 512 MiB). The download is streamed precisely so this cap can abort early instead of buffering an oversized file. Normally surfaced as a FAILURE ConversionResult.

Source

Thrown at docling/service_client/client.py:1966

        if self._allow_private_artifact_urls:
            return
        if not _is_safe_artifact_url(url):
            raise ArtifactDownloadError(
                f"Refusing to download artifact from a non-public URL: {url}."
            )

    @staticmethod
    def _next_redirect_url(current_url: str, response: httpx.Response) -> str:
        location = response.headers.get("location")
        if not location:
            raise ArtifactDownloadError(
                "Artifact download redirect is missing a Location header."
            )
        return str(httpx.URL(current_url).join(location))

    def _check_artifact_size(self, total: int) -> None:
        if total > self._max_artifact_download_bytes:
            raise ArtifactDownloadError(
                "Artifact exceeds max_artifact_download_bytes "
                f"({self._max_artifact_download_bytes} bytes)."
            )

    def _source_to_upload_files(
        self,
        source: Path | DocumentStream,
    ) -> dict[str, tuple[str, IO[bytes], str]]:
        """Build multipart files dict for a sync upload. Passes file handles — no full read."""
        if isinstance(source, Path):
            filename = source.name
            content: IO[bytes] = source.open("rb")
        else:
            filename = source.name
            source.stream.seek(0)
            content = source.stream
        mime = mimetypes.guess_type(filename)[0] or "application/octet-stream"
        return {"files": (filename, content, mime)}

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass a larger max_artifact_download_bytes in the constructor if the artifacts are legitimately big
2. Reduce server-side image quality/resolution options (ImageExportMode, scale) so bundles shrink
3. If unexpected, inspect which artifact is huge — it may indicate a server-side rendering misconfiguration

Example fix

// before
client = DoclingServiceClient(url)  # capped at 512 MiB

// after
client = DoclingServiceClient(url, max_artifact_download_bytes=2 * 1024 * 1024 * 1024)

# estimate artifact size before conversion of similar documents
# e.g. check source file size and image count; then size the cap:
# client = DoclingServiceClient(url, max_artifact_download_bytes=2 * 1024**3)

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

if res.status == ConversionStatus.FAILURE:
    if any('max_artifact_download_bytes' in (e.error_message or '') for e in res.errors):
        client = DoclingServiceClient(url, max_artifact_download_bytes=larger_cap)
        res = retry_conversion(source)

When it happens

Trigger: Converting a document whose referenced-image bundle or other artifact exceeds 512 MiB (or a custom max_artifact_download_bytes) — the check fires mid-stream as chunks accumulate.

Common situations: Image-heavy PDFs with high-DPI page renders; documents with hundreds of embedded photos; the default cap silently hit on large scans.

Related errors

• Unknown EBCDIC codec {encoding!r}.
• The EBCDIC backend needs a layout: set either EbcdicBackendO
• Could not read the EBCDIC layout {self.options.layout_file}.
• Fetching local resources is only allowed when set explicitly
• Local file access requires base_path for directory confineme

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