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, or using the CLI --enable-remote-services.

What it means

OperationNotAllowed guard in ApiVlmModel.__init__: API-based VLM models send document images to a remote service, so Docling refuses to construct the model unless the user has explicitly opted in via enable_remote_services. This is a privacy/consent gate, not a capability check.

Source

Thrown at docling/models/vlm_pipeline_models/api_vlm_model.py:35

)
from docling.utils.profiling import TimeRecorder


class ApiVlmModel(BaseVlmPageModel):
    # Override the vlm_options type annotation from BaseVlmPageModel
    vlm_options: ApiVlmOptions  # type: ignore[assignment]

    def __init__(
        self,
        enabled: bool,
        enable_remote_services: bool,
        vlm_options: ApiVlmOptions,
    ):
        self.enabled = enabled
        self.vlm_options = vlm_options
        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, or using the CLI "
                    "--enable-remote-services."
                )

            self.timeout = self.vlm_options.timeout
            self.concurrency = self.vlm_options.concurrency
            self.params = {
                **self.vlm_options.params,
                "temperature": self.vlm_options.temperature,
            }

    def __call__(
        self, conv_res: ConversionResult, page_batch: Iterable[Page]
    ) -> Iterable[Page]:
        page_list = list(page_batch)
        if not page_list:
            return

View on GitHub (pinned to 61d76f1ff3)

Solutions

Set pipeline_options.enable_remote_services = True in your PipelineOptions when using API VLM models
On the CLI, add --enable-remote-services
If remote calls are not acceptable, switch to a local VLM engine (Transformers, MLX, vLLM) so no opt-in is needed

Example fix

# before
pipeline_options = VlmPipelineOptions(vlm_options=ApiVlmOptions(enabled=True))
# -> OperationNotAllowed
# after
pipeline_options = VlmPipelineOptions(
    enable_remote_services=True,
    vlm_options=ApiVlmOptions(enabled=True),
)

Defensive patterns

Strategy: validation

Validate before calling

from docling.pipeline.options import PipelineOptions
opts = PipelineOptions()
# before constructing the pipeline/model:
assert opts.enable_remote_services, 'API VLM models require explicit opt-in'

Try / catch

from docling.datamodel.settings import OperationNotAllowed
try:
    converter = DocumentConverter(...)
except OperationNotAllowed:
    # reconfigure with opt-in or fall back to a local engine
    ...

Prevention

Centralize enable_remote_services in one config object shared by CLI and SDK paths
Add a startup check: if using API VLM options, fail fast when the flag is unset
Treat this error as a consent gate — do not silence it in shared libraries

When it happens

Trigger: Configuring a VlmPipeline (or ApiVlmOptions-based model) with enabled=True while PipelineOptions.enable_remote_services is left at its default False; or running the CLI with an API VLM model without --enable-remote-services.

Common situations: Following a VLM quickstart that forgets the opt-in flag; CI runs that clone defaults from a template without the remote-services switch; teams whose data-residency policy forbids remote calls and hit this deliberately.

Related errors

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