zylon-ai/private-gpt · error · ValueError

API base URL and poll interval must be provided in async mod

Error message

API base URL and poll interval must be provided in async mode

What it means

Raised by AsyncDoclingClient.__init__ when neither the constructor arguments nor the Docling settings provide an API base URL and a poll interval. The async client drives Docling's task-based API by submitting a job and repeatedly polling /status/poll/{task_id}, so both values are structurally required before any request can be made. Note the constructor uses `or` fallbacks against settings.docling.api_base and settings.docling.pool_interval, so an empty string or 0 passed explicitly also falls through to settings, and the check fires only if the settings value is also falsy.

Source

Thrown at private_gpt/components/readers/docling/api_clients.py:397

    base_url: str = Field(description="Base URL for the Docling API")
    poll_interval: float = Field(description="Polling interval in seconds", default=5.0)
    poll_timeout: float | None = Field(
        description="Polling timeout in seconds", default=None
    )

    def __init__(
        self,
        settings: DoclingConfig,
        api_base: str | None = None,
        poll_interval: float | None = None,
        poll_timeout: float | None = None,
    ):
        api_base = api_base or settings.api_base
        poll_interval = poll_interval or settings.pool_interval
        poll_timeout = poll_timeout or settings.pool_timeout

        if not api_base or not poll_interval:
            raise ValueError(
                "API base URL and poll interval must be provided in async mode"
            )

        super().__init__(
            docling_settings=settings,
            base_url=_build_api_base_url(
                api_base or settings.api_base, settings.api_version
            ),
            poll_interval=poll_interval or settings.pool_interval,
            poll_timeout=poll_timeout or settings.pool_timeout,
        )

    @retry(is_async=True, tries=_MAX_RETRIES, jitter=_JITTER, logger=logger)
    async def _submit_task(
        self, file_name: str, file_bytes: bytes, **kwargs: Any
    ) -> str:
        file_base64 = base64.b64encode(file_bytes).decode("utf-8")
        headers = _build_request_headers(self.docling_settings)

View on GitHub (pinned to 4a030776a3)

Solutions

Set both values in settings.yaml under docling: api_base: http://localhost:5001 and pool_interval: 5 (or your server URL).
Or pass them explicitly: AsyncDoclingClient(settings, api_base='http://localhost:5001', poll_interval=5.0).
If building DoclingConfig programmatically, ensure pool_interval is set (remember the field is named pool_interval, not poll_interval, in settings).
Note poll_timeout is optional: leaving pool_timeout unset means the client polls forever (the while loop condition `not self.poll_timeout` never breaks), so set docling.pool_timeout if you want bounded waits.

Example fix

# before
client = AsyncDoclingClient(settings)  # settings.docling.pool_interval is None

# after (settings.yaml)
# docling:
#   api_base: http://localhost:5001
#   pool_interval: 5
#   pool_timeout: 600
# or in code
client = AsyncDoclingClient(settings, api_base='http://localhost:5001', poll_interval=5.0, poll_timeout=600.0)

Defensive patterns

Strategy: validation

Validate before calling

from private_gpt.components.readers.docling.api_clients import AsyncDoclingClient

def assert_async_docling_ready(cfg) -> None:
    if not cfg.api_base:
        raise SystemExit("settings.docling.api_base is required for the async Docling client")
    if not cfg.pool_interval:
        raise SystemExit("settings.docling.pool_interval is required for the async Docling client")

assert_async_docling_ready(settings().docling)

Try / catch

try:
    client = AsyncDoclingClient(docling_cfg)
except ValueError as e:
    if "async mode" in str(e):
        # configuration problem: fix settings, do not retry
        raise ConfigurationError(str(e)) from e
    raise

Prevention

Add a startup check that settings.docling.api_base and docling.pool_interval are truthy before constructing AsyncDoclingClient.
Remember settings field names use pool_interval/pool_timeout while constructor args use poll_interval/poll_timeout.
Set pool_timeout explicitly unless you intend infinite polling.

When it happens

Trigger: Instantiating AsyncDoclingClient(settings) where settings.docling.api_base or settings.docling.pool_interval is unset/None/empty (e.g., a settings.yaml that overrides the docling block and drops pool_interval), or passing api_base='' / poll_interval=0 explicitly while settings are also empty. Happens at client construction time, before any network call.

Common situations: Custom settings.yaml that sets only docling.api_base but omits docling.pool_interval (the default only applies when the whole docling block is untouched); env-var-driven configs that blank out values; code that builds DoclingConfig programmatically with only some fields; copy-paste from LocalDoclingClient examples where polling is not needed.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/92d5ab64c86562bb. Report an issue: GitHub.