docling-project/docling · error · OperationNotAllowed

Connections to remote services are only allowed when set exp

Error message

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

What it means

The ApiKserveV2ObjectDetectionEngine constructor raises OperationNotAllowed when the enable_remote_services flag is False. Docling blocks any engine that connects to a remote KServe v2 inference server unless the user explicitly opts in, as a safety measure against unintended network calls. The flag comes from pipeline_options.enable_remote_services on the standard PipelineOptions object.

Source

Thrown at docling/models/inference_engines/object_detection/api_kserve_v2_engine.py:60

        accelerator_options: AcceleratorOptions,
        artifacts_path: Optional[Union[Path, str]] = None,
    ):
        super().__init__(
            options=options,
            model_config=model_config,
            accelerator_options=accelerator_options,
            artifacts_path=artifacts_path,
        )
        self.options: ApiKserveV2ObjectDetectionEngineOptions = options
        self._kserve_client: Optional[KserveV2Client] = None
        self._input_images_name: Optional[str] = None
        self._input_orig_target_sizes_name: Optional[str] = None
        self._output_labels_name: Optional[str] = None
        self._output_boxes_name: Optional[str] = None
        self._output_scores_name: Optional[str] = None

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

    def _resolve_model_name(self) -> str:
        if self.options.model_name:
            return self.options.model_name

        return self._repo_id.replace("/", "--")

    def _resolve_model_version(self) -> Optional[str]:
        return self.options.model_version

    def _resolve_tensor_names(self) -> tuple[str, str, str, str, str]:
        if self._kserve_client is None:
            raise RuntimeError("KServe v2 client is not initialized.")

        metadata = self._kserve_client.get_model_metadata()

View on GitHub (pinned to 61d76f1ff3)

Solutions

Set pipeline_options.enable_remote_services = True in your PipelineOptions before constructing the pipeline.
Verify you actually intend to call the remote KServe endpoint (URL, credentials, network reachability) since enabling the flag authorizes outbound connections.
If you did not want a remote call, switch engine_type back to ONNXRUNTIME or TRANSFORMERS so everything runs locally.

Example fix

// before
pipeline_options = StandardPipelineOptions()
pipeline_options.features.layout.object_detection = True
pipeline_options.features.layout.object_detection_engine_options = ApiKserveV2ObjectDetectionEngineOptions(url="https://kserve.example.com")

// after
pipeline_options = StandardPipelineOptions()
pipeline_options.enable_remote_services = True
pipeline_options.features.layout.object_detection = True
pipeline_options.features.layout.object_detection_engine_options = ApiKserveV2ObjectDetectionEngineOptions(url="https://kserve.example.com")

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.pipeline_options import PdfPipelineOptions

if opts.engine_type == ObjectDetectionEngineType.API_KSERVE_V2 and not pipeline_options.enable_remote_services:
    raise SystemExit("Set pipeline_options.enable_remote_services=True before using the KServe engine")

Try / catch

from docling.datamodel.settings import settings  # OperationNotAllowed lives in doclingcore exceptions in some versions
try:
    engine = ApiKserveV2ObjectDetectionEngine(enable_remote_services=opts.enable_remote_services, options=engine_opts)
except OperationNotAllowed as e:
    raise ConfigurationError(f"Remote services disabled: {e}") from e

Prevention

Treat enable_remote_services=True as a deliberate security decision; default to local engines.
Centralize pipeline option construction in one config function so the flag is set in exactly one place.
Add a startup check that fails fast when a remote engine type is configured without the flag.

When it happens

Trigger: Creating a StandardPipelineOptions (or ObjectDetectionPipeline options) with features.layout.object_detection.engine_options.engine_type = ObjectDetectionEngineType.API_KSERVE_V2 while pipeline_options.enable_remote_services is left at its default False, then running the pipeline / instantiating the engine.

Common situations: Copying an example that uses a KServe-hosted RT-DETR model without also copying the enable_remote_services=True line; assuming remote engines work out of the box like local ONNX ones; CI configs generated from templates that omit the flag.

Related errors

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