{"record":{"id":"51719de912c703d8","repo":"docling-project/docling","slug":"api-runtime-requires-a-url","errorCode":null,"errorMessage":"API runtime requires a URL","messagePattern":"API runtime requires a URL","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/api_openai_compatible_engine.py","lineNumber":95,"sourceCode":"        # User-supplied params always win; if provided, model-spec defaults are\n        # not mixed in (prevents conflicts for vendor-specific keys like model_id).\n        self.user_params: dict = self.options.params.copy()\n\n    def initialize(self) -> None:\n        \"\"\"Initialize the API engine.\n\n        For API runtimes, initialization is minimal - just validate options.\n        \"\"\"\n        if self._initialized:\n            return\n\n        _log.info(\n            f\"Initializing API VLM inference engine (endpoint: {self.options.url})\"\n        )\n\n        # Validate that we have a URL\n        if not self.options.url:\n            raise ValueError(\"API runtime requires a URL\")\n\n        self._initialized = True\n        _log.info(\"API runtime initialized\")\n\n    def predict_batch(self, input_batch: List[VlmEngineInput]) -> List[VlmEngineOutput]:\n        \"\"\"Run inference on a batch of inputs using concurrent API requests.\n\n        This method processes multiple images concurrently using a thread pool,\n        which can significantly improve throughput for API-based runtimes.\n\n        Args:\n            input_batch: List of inputs to process\n\n        Returns:\n            List of outputs, one per input\n        \"\"\"\n        if not self._initialized:\n            self.initialize()","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/api_openai_compatible_engine.py#L77-L113","documentation":"The API VLM inference engine (OpenAI-compatible HTTP runtime) requires an endpoint URL, and initialization fails when options.url is empty. The URL normally comes from ApiVlmEngineOptions.url or from the chosen VlmModelSpec (e.g. LM Studio on port 1234, vLLM on 8000, Ollama on 11434). An empty value means the engine has nowhere to send chat/completions requests.","triggerScenarios":"Calling ApiVlmEngine.initialize() (directly or lazily via predict_batch) when options.url is falsy — e.g. constructing ApiVlmEngineOptions without a url, or using a model spec whose url was cleared/overridden to an empty string.","commonSituations":"Pointing a VLM pipeline at a custom local server but forgetting to set the url; building options programmatically from a config dict where the url key is missing; a model spec that has no default URL for the chosen API variant.","solutions":["Set an explicit endpoint, e.g. ApiVlmEngineOptions(url='http://localhost:8000/v1/chat/completions')","Or pick a predefined model spec (e.g. SMOLDOCLING_VLM or an Ollama/vLLM spec) that carries a default url","Verify the URL points at an OpenAI-compatible /v1/chat/completions route and that the server is running"],"exampleFix":"# before\noptions = ApiVlmEngineOptions(engine_type=VlmEngineType.API)\n\n# after\nfrom pydantic import AnyUrl\noptions = ApiVlmEngineOptions(\n    engine_type=VlmEngineType.API,\n    url=AnyUrl('http://localhost:8000/v1/chat/completions'),\n)","handlingStrategy":"validation","validationCode":"from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions\n\nopts = ApiVlmEngineOptions(url='http://localhost:8000/v1/chat/completions')\nassert opts.url, 'API engine requires a non-empty url'\nimport urllib.request\nurllib.request.urlopen(str(opts.url).rsplit('/', 1)[0] + '/models', timeout=3)  # optional reachability probe","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept ValueError as e:\n    if 'requires a URL' in str(e):\n        raise SystemExit(f'Missing VLM endpoint URL: {e}') from e\n    raise","preventionTips":["Always set url explicitly in ApiVlmEngineOptions; do not rely on a spec default you have not verified","Keep endpoint URLs in one config location and assert they are non-empty at app startup","Health-check the OpenAI-compatible server (/v1/models) before starting a conversion job"],"tags":["vlm","api","configuration","url","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}