docling-project/docling · error · ValueError

{name} must be between 1 and {MAX_CONCURRENCY_LIMIT}, got {v

Error message

{name} must be between 1 and {MAX_CONCURRENCY_LIMIT}, got {value}.

What it means

The sync service client caps concurrent operations (websockets, pollers, submissions) between 1 and MAX_CONCURRENCY_LIMIT (512 in this codebase). _validate_concurrency checks every user-supplied concurrency setting and raises ValueError naming the parameter and the offending value when out of range. This prevents zero/negative worker counts and resource exhaustion from unbounded parallelism.

Source

Thrown at docling/service_client/client.py:541

    ) -> Path | HttpSourceRequest | DocumentStream:
        if isinstance(source, (Path, HttpSourceRequest, DocumentStream)):
            return source
        try:
            http_url = TypeAdapter(AnyHttpUrl).validate_python(source)
            return HttpSourceRequest(url=str(http_url), headers={})
        except ValidationError:
            if "://" in source:
                scheme = source.split("://", 1)[0].lower()
                if scheme not in ("http", "https"):
                    raise ValueError(
                        f"Unsupported URL scheme: '{scheme}'. Only http:// and https:// are supported."
                    )
            return TypeAdapter(Path).validate_python(source)

    @staticmethod
    def _validate_concurrency(value: int, *, name: str) -> int:
        if value < 1 or value > MAX_CONCURRENCY_LIMIT:
            raise ValueError(
                f"{name} must be between 1 and {MAX_CONCURRENCY_LIMIT}, got {value}."
            )
        return value

    @staticmethod
    def _normalize_exception(exc: BaseException) -> Exception:
        if isinstance(exc, Exception):
            return exc
        return RuntimeError(str(exc))

    def _submit_and_retrieve_many_uses_websocket_wait(
        self,
        max_in_flight: int,
    ) -> bool:
        return (
            self._status_watcher_kind == StatusWatcherKind.WEBSOCKET
            and max_in_flight <= SUBMIT_AND_RETRIEVE_MANY_MAX_IN_FLIGHT_WEBSOCKETS
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Clamp your concurrency value to 1..512 before constructing the client (e.g. max(1, min(value, 512))).
2. Use a sensible fixed value based on service capacity rather than unbounded scaling.
3. Validate env-derived settings early with a clear error of your own.

Example fix

# before
client = DocumentConverterClient(url, max_concurrency=int(os.environ.get('WORKERS', 0)))  # 0 -> ValueError

# after
workers = max(1, min(int(os.environ.get('WORKERS', 8)), 512))
client = DocumentConverterClient(url, max_concurrency=workers)

MAX_CONCURRENCY_LIMIT = 512
workers = max(1, min(int(cfg.get('workers', 8)), MAX_CONCURRENCY_LIMIT))

When it happens

Trigger: Passing max_concurrency=0 or a negative number to the client constructor; setting websocket/poll concurrency above 512; computing concurrency from a formula (e.g. os.cpu_count()*k) that can exceed the cap or yield 0 in containers.

Common situations: Deriving concurrency from environment variables that default to 0 when unset; large batch scripts wanting 'unlimited' parallelism; containerized runs where cpu_count reports unexpected values.

Related errors

• Archive exceeds maximum member count limit of {self.options.
• submit_batch() requires either 'target' or 'targets'.
• submit_batch() received both 'target' and 'targets'; supply
• Response schema mismatch — client and server versions may di
• Unsupported URL scheme: '{scheme}'. Only http:// and https:/

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