{"record":{"id":"76aa1012f4337707","repo":"docling-project/docling","slug":"fetching-remote-resources-is-only-allowed-when-set","errorCode":null,"errorMessage":"Fetching remote resources is only allowed when set explicitly. Set options.enable_remote_fetch=True.","messagePattern":"Fetching remote resources is only allowed when set explicitly\\. Set options\\.enable_remote_fetch=True\\.","errorType":"exception","errorClass":"OperationNotAllowed","httpStatus":null,"severity":"warning","filePath":"docling/backend/utils/image_resource_loader.py","lineNumber":196,"sourceCode":"\n        return None\n\n    def load_image_ref(self, src: str, base_path: Optional[str]) -> Optional[ImageRef]:\n        \"\"\"Resolve ``src`` against ``base_path`` and decode it into an ImageRef.\"\"\"\n        return self.create_image_ref(\n            self.resolve_relative_path(src, base_path), base_path\n        )\n\n    def load_image_data(\n        self, src_loc: str, base_path: Optional[str]\n    ) -> Optional[bytes]:\n        if src_loc.lower().endswith(\".svg\"):\n            _log.debug(f\"Skipping SVG file: {src_loc}\")\n            return None\n\n        if ImageResourceLoader.is_remote_url(src_loc):\n            if not self.enable_remote_fetch:\n                raise OperationNotAllowed(\n                    \"Fetching remote resources is only allowed when set explicitly. \"\n                    \"Set options.enable_remote_fetch=True.\"\n                )\n\n            validate_url_safety(src_loc)\n\n            max_size = self.max_remote_image_bytes\n            headers = {\"Range\": f\"bytes=0-{max_size - 1}\"}\n\n            # Merge custom headers from options if provided\n            if self.headers:\n                headers.update(self.headers)\n\n            # Create session with redirect limit\n            session = requests.Session()\n            session.max_redirects = self.max_redirects\n\n            # Hook to validate each redirect target","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/utils/image_resource_loader.py#L178-L214","documentation":"OperationNotAllowed (docling/exceptions.py:18) raised in load_image_data when an image src is a remote URL and the loader was constructed with enable_remote_fetch=False (the default). It is a deliberate opt-in gate: documents can reference remote images, but docling will not perform network fetches unless explicitly allowed.","triggerScenarios":"Converting HTML/other declarative documents whose <img src> is an http(s) URL while ImageResourceLoader/backend options leave enable_remote_fetch at its default False. The check runs before validate_url_safety and before any Range request is issued.","commonSituations":"First-time HTML conversion hitting external CDNs; security-conscious deployments where remote fetch stays off and images are expected to be skipped; upgrading pipelines where images suddenly appear broken after the opt-in was introduced.","solutions":["Opt in explicitly: set enable_remote_fetch=True on ImageResourceLoader (or the backend/pipeline option that forwards it) when the environment allows outbound HTTPS.","If you must not fetch, pre-download and localize the images, then reference them relatively with enable_local_fetch=True and a base_path.","Combine with max_remote_image_bytes and custom headers if the image host needs auth/Range support.","Never enable remote fetch on untrusted documents without the built-in SSRF checks staying active."],"exampleFix":"# before\nloader = ImageResourceLoader()  # enable_remote_fetch defaults to False\ndata = loader.load_image_data('https://cdn.example.com/logo.png', base)\n# OperationNotAllowed\n\n# after\nloader = ImageResourceLoader(enable_remote_fetch=True,\n                              max_remote_image_bytes=5 * 1024 * 1024)\ndata = loader.load_image_data('https://cdn.example.com/logo.png', base)","handlingStrategy":"fallback","validationCode":"from docling.backend.utils.image_resource_loader import ImageResourceLoader\nassert ImageResourceLoader.is_remote_url(src) is False or FETCH_REMOTE, 'enable remote fetch or localize images'","typeGuard":"def needs_remote(loader: ImageResourceLoader, src: str) -> bool:\n    return ImageResourceLoader.is_remote_url(src) and not loader.enable_remote_fetch","tryCatchPattern":"from docling.exceptions import OperationNotAllowed\ntry:\n    data = loader.load_image_data(src, base)\nexcept OperationNotAllowed:\n    data = None  # document references remote image; remote fetch not permitted","preventionTips":["Set enable_remote_fetch=True only in environments where outbound HTTPS is sanctioned","Pre-download and localize remote images when fetch is disabled","Keep the SSRF validation active whenever remote fetch is enabled"],"tags":["remote-fetch","security","network","images","opt-in"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}