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

Docling refuses to connect to remote inference services unless the user explicitly opts in. Constructing the KServe v2 image-classification engine without enable_remote_services=True raises OperationNotAllowed. This is a deliberate privacy/data-boundary guard: document content would otherwise be sent to an external endpoint without consent.

Source

Thrown at docling/models/inference_engines/image_classification/api_kserve_v2_engine.py:56

        enable_remote_services: bool,
        options: ApiKserveV2ImageClassificationEngineOptions,
        model_config: Optional[EngineModelConfig] = None,
        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: ApiKserveV2ImageClassificationEngineOptions = options
        self._kserve_client: Optional[KserveV2Client] = None
        self._input_name: Optional[str] = None
        self._output_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]:
        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

1. Set enable_remote_services=True in your pipeline options before using the ApiKserveV2 image-classification engine (e.g. pipeline_options.enable_remote_services = True).
2. If you did not intend remote calls, keep the flag False and use a local engine type (ONNXRUNTIME or TRANSFORMERS) instead.
3. If setting it programmatically, ensure the flag is propagated to the factory call (create_..._engine(enable_remote_services=...)) and not overridden elsewhere.

Example fix

# before
pipeline_options.enable_remote_services = False
options = ImageClassifierPipelineOptions(
    engine_options=ApiKserveV2ImageClassificationEngineOptions(...)
)

# after
pipeline_options.enable_remote_services = True
options = ImageClassifierPipelineOptions(
    engine_options=ApiKserveV2ImageClassificationEngineOptions(...)
)

from docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions

if isinstance(options, ApiKserveV2ImageClassificationEngineOptions) and not enable_remote_services:
    raise PermissionError(
        "enable_remote_services must be True to use the KServe v2 engine"
    )

from docling.exceptions import OperationNotAllowed

try:
    engine.initialize()
except OperationNotAllowed as e:
    # config issue: set the flag or switch to a local engine; do not retry
    raise SystemExit(f"config error: {e}") from e

When it happens

Trigger: Creating ApiKserveV2ImageClassificationEngine (directly or via the engine factory with engine_type=API_KSERVE_V2) while the enable_remote_services flag passed down from pipeline_options is False/unset.

Common situations: Switching ImageClassifier pipeline options to the ApiKserveV2 engine without setting pipeline_options.enable_remote_services=True; a shared config where the flag was disabled for local-only operation; new users trying the remote engine from an example without the opt-in 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
• Invalid metadata response from {self.model_metadata_url}: {e
• Expected image-classification model metadata to expose at le

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