docling-project/docling · error · ValueError

API runtime requires a URL

Error message

API runtime requires a URL

What it means

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.

Source

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

        # 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.

        For API runtimes, initialization is minimal - just validate options.
        """
        if self._initialized:
            return

        _log.info(
            f"Initializing API VLM inference engine (endpoint: {self.options.url})"
        )

        # Validate that we have a URL
        if not self.options.url:
            raise ValueError("API runtime requires a URL")

        self._initialized = True
        _log.info("API runtime initialized")

    def predict_batch(self, input_batch: List[VlmEngineInput]) -> List[VlmEngineOutput]:
        """Run inference on a batch of inputs using concurrent API requests.

        This method processes multiple images concurrently using a thread pool,
        which can significantly improve throughput for API-based runtimes.

        Args:
            input_batch: List of inputs to process

        Returns:
            List of outputs, one per input
        """
        if not self._initialized:
            self.initialize()

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set an explicit endpoint, e.g. ApiVlmEngineOptions(url='http://localhost:8000/v1/chat/completions')
2. Or pick a predefined model spec (e.g. SMOLDOCLING_VLM or an Ollama/vLLM spec) that carries a default url
3. Verify the URL points at an OpenAI-compatible /v1/chat/completions route and that the server is running

Example fix

# before
options = ApiVlmEngineOptions(engine_type=VlmEngineType.API)

# after
from pydantic import AnyUrl
options = ApiVlmEngineOptions(
    engine_type=VlmEngineType.API,
    url=AnyUrl('http://localhost:8000/v1/chat/completions'),
)

from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions

opts = ApiVlmEngineOptions(url='http://localhost:8000/v1/chat/completions')
assert opts.url, 'API engine requires a non-empty url'
import urllib.request
urllib.request.urlopen(str(opts.url).rsplit('/', 1)[0] + '/models', timeout=3)  # optional reachability probe

try:
    engine.initialize()
except ValueError as e:
    if 'requires a URL' in str(e):
        raise SystemExit(f'Missing VLM endpoint URL: {e}') from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown prompt style: {prompt_style}. Valid values are {', '
• Expected ApiVlmEngineOptions, got {type(options)}
• Prompt list length ({len(prompt)}) must match image count ({
• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot specify both vlm_pipeline_preset and vlm_pipeline_cus

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