{"record":{"id":"3ff51e8576a67335","repo":"docling-project/docling","slug":"artifact-exceeds-max-artifact-download-bytes-sel","errorCode":null,"errorMessage":"Artifact exceeds max_artifact_download_bytes ({self._max_artifact_download_bytes} bytes).","messagePattern":"Artifact exceeds max_artifact_download_bytes \\((.+?) bytes\\)\\.","errorType":"exception","errorClass":"ArtifactDownloadError","httpStatus":null,"severity":"error","filePath":"docling/service_client/client.py","lineNumber":1966,"sourceCode":"        if self._allow_private_artifact_urls:\n            return\n        if not _is_safe_artifact_url(url):\n            raise ArtifactDownloadError(\n                f\"Refusing to download artifact from a non-public URL: {url}.\"\n            )\n\n    @staticmethod\n    def _next_redirect_url(current_url: str, response: httpx.Response) -> str:\n        location = response.headers.get(\"location\")\n        if not location:\n            raise ArtifactDownloadError(\n                \"Artifact download redirect is missing a Location header.\"\n            )\n        return str(httpx.URL(current_url).join(location))\n\n    def _check_artifact_size(self, total: int) -> None:\n        if total > self._max_artifact_download_bytes:\n            raise ArtifactDownloadError(\n                \"Artifact exceeds max_artifact_download_bytes \"\n                f\"({self._max_artifact_download_bytes} bytes).\"\n            )\n\n    def _source_to_upload_files(\n        self,\n        source: Path | DocumentStream,\n    ) -> dict[str, tuple[str, IO[bytes], str]]:\n        \"\"\"Build multipart files dict for a sync upload. Passes file handles — no full read.\"\"\"\n        if isinstance(source, Path):\n            filename = source.name\n            content: IO[bytes] = source.open(\"rb\")\n        else:\n            filename = source.name\n            source.stream.seek(0)\n            content = source.stream\n        mime = mimetypes.guess_type(filename)[0] or \"application/octet-stream\"\n        return {\"files\": (filename, content, mime)}","sourceCodeStart":1948,"sourceCodeEnd":1984,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/client.py#L1948-L1984","documentation":"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.","triggerScenarios":"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.","commonSituations":"Image-heavy PDFs with high-DPI page renders; documents with hundreds of embedded photos; the default cap silently hit on large scans.","solutions":["Pass a larger max_artifact_download_bytes in the constructor if the artifacts are legitimately big","Reduce server-side image quality/resolution options (ImageExportMode, scale) so bundles shrink","If unexpected, inspect which artifact is huge — it may indicate a server-side rendering misconfiguration"],"exampleFix":"// before\nclient = DoclingServiceClient(url)  # capped at 512 MiB\n\n// after\nclient = DoclingServiceClient(url, max_artifact_download_bytes=2 * 1024 * 1024 * 1024)","handlingStrategy":"validation","validationCode":"# estimate artifact size before conversion of similar documents\n# e.g. check source file size and image count; then size the cap:\n# client = DoclingServiceClient(url, max_artifact_download_bytes=2 * 1024**3)","typeGuard":"def is_artifact_download_error(exc: BaseException) -> bool:\n    return isinstance(exc, ArtifactDownloadError)","tryCatchPattern":"if res.status == ConversionStatus.FAILURE:\n    if any('max_artifact_download_bytes' in (e.error_message or '') for e in res.errors):\n        client = DoclingServiceClient(url, max_artifact_download_bytes=larger_cap)\n        res = retry_conversion(source)","preventionTips":["Set max_artifact_download_bytes explicitly for image-heavy workloads","Lower server-side image resolution settings to shrink bundles"],"tags":["resource-limits","artifact-download","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}