docling-project/docling · error · OperationNotAllowed

Connections to remote services is only allowed when set expl

Error message

Connections to remote services is only allowed when set explicitly. pipeline_options.enable_remote_services=True.

What it means

The API-based picture description model calls out to a remote HTTP endpoint. Because that exfiltrates document content, Docling refuses to run it unless the user explicitly opts in with enable_remote_services=True on the pipeline options; otherwise OperationNotAllowed is raised at model init.

Source

Thrown at docling/models/stages/picture_description/picture_description_api_model.py:46

        enabled: bool,
        enable_remote_services: bool,
        artifacts_path: Optional[Union[Path, str]],
        options: PictureDescriptionApiOptions,
        accelerator_options: AcceleratorOptions,
    ):
        super().__init__(
            enabled=enabled,
            enable_remote_services=enable_remote_services,
            artifacts_path=artifacts_path,
            options=options,
            accelerator_options=accelerator_options,
        )
        self.options: PictureDescriptionApiOptions
        self.concurrency = self.options.concurrency

        if self.enabled:
            if not enable_remote_services:
                raise OperationNotAllowed(
                    "Connections to remote services is only allowed when set explicitly. "
                    "pipeline_options.enable_remote_services=True."
                )

    def _annotate_images(
        self, images: Iterable[Image.Image]
    ) -> Iterable[ApiImageRequestResult]:
        # Note: technically we could make a batch request here,
        # but not all APIs will allow for it. For example, vllm won't allow more than 1.
        def _api_request(image):
            return api_image_request(
                image=image,
                prompt=self.options.prompt,
                url=self.options.url,
                timeout=self.options.timeout,
                headers=self.options.headers,
                usage_response_key=self.options.usage_response_key,
                **self.options.params,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Opt in explicitly: pipeline_options = PdfPipelineOptions(); pipeline_options.enable_remote_services = True.
2. If the service is actually local, still set the flag (it governs any non-local socket), or switch to a local VLM model to avoid remote calls entirely.
3. For privacy-sensitive documents, keep the flag off and use a locally hosted model (picture_description_vlm_model).

Example fix

# before
pipeline_options.ocr_options ...
model = PictureDescriptionApiModel(options=PictureDescriptionApiOptions(url=...))

# after
pipeline_options.enable_remote_services = True
model = PictureDescriptionApiModel(
    enabled=True,
    enable_remote_services=True,
    options=PictureDescriptionApiOptions(url=...),
)

if options.url and not pipeline_options.enable_remote_services:
    raise PermissionError(
        "picture description API requires explicit opt-in: "
        "pipeline_options.enable_remote_services = True"
    )

from docling_core.transforms.node_errors import OperationNotAllowed

try:
    model = PictureDescriptionApiModel(options=opts, enable_remote_services=False)
except OperationNotAllowed:
    log.error("remote calls blocked; enable_remote_services=True required for API descriptions")
    raise

When it happens

Trigger: Using PictureDescriptionApiOptions (e.g. pointing at an OpenAI-compatible/vLLM endpoint) while pipeline_options.enable_remote_services is left at its default False.

Common situations: Copy-pasting examples that configure picture_description_api_model without adding enable_remote_services=True; privacy-conscious defaults surprising users who intended to call their own local-but-remote-hosted vLLM service.

Related errors

• Connections to remote services are only allowed when set exp
• Connections to remote services are only allowed when set exp
• Connections to remote services is only allowed when set expl
• Connections to remote services is only allowed when set expl
• Fetching local resources is only allowed when set explicitly

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