docling-project/docling · warning · OperationNotAllowed

Fetching remote resources is only allowed when set explicitl

Error message

Fetching remote resources is only allowed when set explicitly. Set options.enable_remote_fetch=True.

What it means

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.

Source

Thrown at docling/backend/utils/image_resource_loader.py:196

        return None

    def load_image_ref(self, src: str, base_path: Optional[str]) -> Optional[ImageRef]:
        """Resolve ``src`` against ``base_path`` and decode it into an ImageRef."""
        return self.create_image_ref(
            self.resolve_relative_path(src, base_path), base_path
        )

    def load_image_data(
        self, src_loc: str, base_path: Optional[str]
    ) -> Optional[bytes]:
        if src_loc.lower().endswith(".svg"):
            _log.debug(f"Skipping SVG file: {src_loc}")
            return None

        if ImageResourceLoader.is_remote_url(src_loc):
            if not self.enable_remote_fetch:
                raise OperationNotAllowed(
                    "Fetching remote resources is only allowed when set explicitly. "
                    "Set options.enable_remote_fetch=True."
                )

            validate_url_safety(src_loc)

            max_size = self.max_remote_image_bytes
            headers = {"Range": f"bytes=0-{max_size - 1}"}

            # Merge custom headers from options if provided
            if self.headers:
                headers.update(self.headers)

            # Create session with redirect limit
            session = requests.Session()
            session.max_redirects = self.max_redirects

            # Hook to validate each redirect target

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Opt in explicitly: set enable_remote_fetch=True on ImageResourceLoader (or the backend/pipeline option that forwards it) when the environment allows outbound HTTPS.
2. If you must not fetch, pre-download and localize the images, then reference them relatively with enable_local_fetch=True and a base_path.
3. Combine with max_remote_image_bytes and custom headers if the image host needs auth/Range support.
4. Never enable remote fetch on untrusted documents without the built-in SSRF checks staying active.

Example fix

# before
loader = ImageResourceLoader()  # enable_remote_fetch defaults to False
data = loader.load_image_data('https://cdn.example.com/logo.png', base)
# OperationNotAllowed

# after
loader = ImageResourceLoader(enable_remote_fetch=True,
                              max_remote_image_bytes=5 * 1024 * 1024)
data = loader.load_image_data('https://cdn.example.com/logo.png', base)

from docling.backend.utils.image_resource_loader import ImageResourceLoader
assert ImageResourceLoader.is_remote_url(src) is False or FETCH_REMOTE, 'enable remote fetch or localize images'

def needs_remote(loader: ImageResourceLoader, src: str) -> bool:
    return ImageResourceLoader.is_remote_url(src) and not loader.enable_remote_fetch

from docling.exceptions import OperationNotAllowed
try:
    data = loader.load_image_data(src, base)
except OperationNotAllowed:
    data = None  # document references remote image; remote fetch not permitted

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Access to restricted IP address not allowed: {ip}
• URL must contain a valid hostname
• Cannot resolve hostname: {hostname}
• Path traversal blocked: '{loc}' resolves outside base direct
• Resource size exceeds limit: {content_length} bytes

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