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 OpenAI-compatible VLM engine constructor raises OperationNotAllowed unless enable_remote_services is True. Like the KServe object-detection engine, any Docling engine that calls out to a remote inference service requires the explicit pipeline_options.enable_remote_services opt-in, preventing accidental API calls (and cost/data leakage) to external endpoints.

Source

Thrown at docling/models/inference_engines/vlm/api_openai_compatible_engine.py:64

        enable_remote_services: bool,
        options: ApiVlmEngineOptions,
        model_config: Optional["EngineModelConfig"] = None,
    ):
        """Initialize the API engine.

        Args:
            options: API-specific runtime options
            model_config: Model configuration (repo_id, revision, extra_config)
        """
        super().__init__(options, model_config=model_config)
        self._initialized: bool = False
        self.enable_remote_services = enable_remote_services
        self.options: ApiVlmEngineOptions = options
        self.model_api_params: dict[str, object] = {}
        self.user_params: dict[str, object] = self.options.params.copy()

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

        # Store model-spec api_params and user params separately so that the
        # correct priority order can be applied in predict_batch:
        #   model_spec defaults < request-level generation settings < user params
        if model_config and "api_params" in model_config.extra_config:
            self.model_api_params: dict = model_config.extra_config["api_params"].copy()
        else:
            self.model_api_params = {}

        # User-supplied params always win; if provided, model-spec defaults are
        # not mixed in (prevents conflicts for vendor-specific keys like model_id).
        self.user_params: dict = self.options.params.copy()

    def initialize(self) -> None:
        """Initialize the API engine.

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set pipeline_options.enable_remote_services = True before building the converter/pipeline.
2. Confirm the target URL and API key are correct and intended — enabling the flag authorizes outbound calls to the OpenAI-compatible endpoint.
3. Keep the flag False for purely local engines (onnx/transformers) so remote calls remain impossible by default.

Example fix

# before
pipeline_options = PdfPipelineOptions()
pipeline_options.vlm_options = VlmPipelineOptions(engine_options=ApiVlmEngineOptions(url=...))

# after
pipeline_options = PdfPipelineOptions()
pipeline_options.enable_remote_services = True
pipeline_options.vlm_options = VlmPipelineOptions(engine_options=ApiVlmEngineOptions(url=...))

if isinstance(vlm_engine_opts, ApiVlmEngineOptions) and not pipeline_options.enable_remote_services:
    raise SystemExit("Set pipeline_options.enable_remote_services=True to use an OpenAI-compatible VLM endpoint")

def is_remote_vlm_opts(o: object) -> "TypeGuard[ApiVlmEngineOptions]":
    return isinstance(o, ApiVlmEngineOptions)

try:
    converter = DocumentConverter(format_options=fmt_opts)
except OperationNotAllowed as e:
    raise ConfigurationError(f"Remote VLM engine requires enable_remote_services=True: {e}") from e

When it happens

Trigger: Configuring a VLM pipeline with the api_openai_compatible engine (e.g. a vLLM/OpenAI-compatible server URL) while pipeline_options.enable_remote_services is left False, then creating the pipeline.

Common situations: Adopting local-only Docling configs into a remote-LLM setup without adding the flag; assuming local vLLM endpoints are exempt (they are not — the flag applies regardless of host); CI configs templated without the flag.

Related errors

• 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
• Local file access requires base_path for directory confineme

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