{"record":{"id":"fcdc3cbc4b0c26cc","repo":"docling-project/docling","slug":"name-must-be-between-1-and-max-concurrency-limi","errorCode":null,"errorMessage":"{name} must be between 1 and {MAX_CONCURRENCY_LIMIT}, got {value}.","messagePattern":"(.+?) must be between 1 and (.+?), got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/service_client/client.py","lineNumber":541,"sourceCode":"    ) -> Path | HttpSourceRequest | DocumentStream:\n        if isinstance(source, (Path, HttpSourceRequest, DocumentStream)):\n            return source\n        try:\n            http_url = TypeAdapter(AnyHttpUrl).validate_python(source)\n            return HttpSourceRequest(url=str(http_url), headers={})\n        except ValidationError:\n            if \"://\" in source:\n                scheme = source.split(\"://\", 1)[0].lower()\n                if scheme not in (\"http\", \"https\"):\n                    raise ValueError(\n                        f\"Unsupported URL scheme: '{scheme}'. Only http:// and https:// are supported.\"\n                    )\n            return TypeAdapter(Path).validate_python(source)\n\n    @staticmethod\n    def _validate_concurrency(value: int, *, name: str) -> int:\n        if value < 1 or value > MAX_CONCURRENCY_LIMIT:\n            raise ValueError(\n                f\"{name} must be between 1 and {MAX_CONCURRENCY_LIMIT}, got {value}.\"\n            )\n        return value\n\n    @staticmethod\n    def _normalize_exception(exc: BaseException) -> Exception:\n        if isinstance(exc, Exception):\n            return exc\n        return RuntimeError(str(exc))\n\n    def _submit_and_retrieve_many_uses_websocket_wait(\n        self,\n        max_in_flight: int,\n    ) -> bool:\n        return (\n            self._status_watcher_kind == StatusWatcherKind.WEBSOCKET\n            and max_in_flight <= SUBMIT_AND_RETRIEVE_MANY_MAX_IN_FLIGHT_WEBSOCKETS\n        )","sourceCodeStart":523,"sourceCodeEnd":559,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/client.py#L523-L559","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Clamp your concurrency value to 1..512 before constructing the client (e.g. max(1, min(value, 512))).","Use a sensible fixed value based on service capacity rather than unbounded scaling.","Validate env-derived settings early with a clear error of your own."],"exampleFix":"# before\nclient = DocumentConverterClient(url, max_concurrency=int(os.environ.get('WORKERS', 0)))  # 0 -> ValueError\n\n# after\nworkers = max(1, min(int(os.environ.get('WORKERS', 8)), 512))\nclient = DocumentConverterClient(url, max_concurrency=workers)","handlingStrategy":"validation","validationCode":"MAX_CONCURRENCY_LIMIT = 512\nworkers = max(1, min(int(cfg.get('workers', 8)), MAX_CONCURRENCY_LIMIT))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp env-derived concurrency to 1..512 before constructing the client.","Treat 0 or empty concurrency settings as config errors at startup."],"tags":["service-client","concurrency","validation","limits"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}