{"record":{"id":"db7ad92d1ab9fa0c","repo":"docling-project/docling","slug":"connections-to-remote-services-is-only-allowed-whe-db7ad9","errorCode":null,"errorMessage":"Connections to remote services is only allowed when set explicitly. pipeline_options.enable_remote_services=True, or using the CLI --enable-remote-services.","messagePattern":"Connections to remote services is only allowed when set explicitly\\. pipeline_options\\.enable_remote_services=True, or using the CLI --enable-remote-services\\.","errorType":"exception","errorClass":"OperationNotAllowed","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/api_vlm_model.py","lineNumber":35,"sourceCode":")\nfrom docling.utils.profiling import TimeRecorder\n\n\nclass ApiVlmModel(BaseVlmPageModel):\n    # Override the vlm_options type annotation from BaseVlmPageModel\n    vlm_options: ApiVlmOptions  # type: ignore[assignment]\n\n    def __init__(\n        self,\n        enabled: bool,\n        enable_remote_services: bool,\n        vlm_options: ApiVlmOptions,\n    ):\n        self.enabled = enabled\n        self.vlm_options = vlm_options\n        if self.enabled:\n            if not enable_remote_services:\n                raise OperationNotAllowed(\n                    \"Connections to remote services is only allowed when set explicitly. \"\n                    \"pipeline_options.enable_remote_services=True, or using the CLI \"\n                    \"--enable-remote-services.\"\n                )\n\n            self.timeout = self.vlm_options.timeout\n            self.concurrency = self.vlm_options.concurrency\n            self.params = {\n                **self.vlm_options.params,\n                \"temperature\": self.vlm_options.temperature,\n            }\n\n    def __call__(\n        self, conv_res: ConversionResult, page_batch: Iterable[Page]\n    ) -> Iterable[Page]:\n        page_list = list(page_batch)\n        if not page_list:\n            return","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/api_vlm_model.py#L17-L53","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\npipeline_options = VlmPipelineOptions(vlm_options=ApiVlmOptions(enabled=True))\n# -> OperationNotAllowed\n# after\npipeline_options = VlmPipelineOptions(\n    enable_remote_services=True,\n    vlm_options=ApiVlmOptions(enabled=True),\n)","handlingStrategy":"validation","validationCode":"from docling.pipeline.options import PipelineOptions\nopts = PipelineOptions()\n# before constructing the pipeline/model:\nassert opts.enable_remote_services, 'API VLM models require explicit opt-in'","typeGuard":null,"tryCatchPattern":"from docling.datamodel.settings import OperationNotAllowed\ntry:\n    converter = DocumentConverter(...)\nexcept OperationNotAllowed:\n    # reconfigure with opt-in or fall back to a local engine\n    ...","preventionTips":["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"],"tags":["remote-services","privacy","configuration","vlm"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}