{"record":{"id":"71f103441ef48130","repo":"vllm-project/vllm","slug":"elastic-ep-with-async-eplb-requires-the-nixl-packa","errorCode":null,"errorMessage":"Elastic EP with async EPLB requires the NIXL package. Either install NIXL or set --eplb-config.use_async=false.","messagePattern":"Elastic EP with async EPLB requires the NIXL package\\. Either install NIXL or set --eplb-config\\.use_async=false\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":861,"sourceCode":"        if self.enable_elastic_ep:\n            if not self.enable_eplb:\n                raise ValueError(\"Elastic EP is only supported with enable_eplb=True.\")\n            if self.pipeline_parallel_size > 1:\n                raise ValueError(\n                    \"Elastic EP is not supported with pipeline parallelism \"\n                    f\"(pipeline_parallel_size={self.pipeline_parallel_size}).\"\n                )\n            if self.data_parallel_external_lb or self.data_parallel_hybrid_lb:\n                raise NotImplementedError(\n                    \"Elastic EP is not compatible with data_parallel_external_lb \"\n                    \"or data_parallel_hybrid_lb. Elastic EP relies on a single API \"\n                    \"server and core client to coordinate scale up/down.\"\n                )\n            if self.eplb_config.use_async:\n                from vllm.distributed.nixl_utils import is_nixl_available\n\n                if not is_nixl_available():\n                    raise ValueError(\n                        \"Elastic EP with async EPLB requires the NIXL \"\n                        \"package. Either install NIXL or set \"\n                        \"--eplb-config.use_async=false.\"\n                    )\n\n        if self.data_parallel_size > 1 or self.data_parallel_size_local == 0:\n            # Data parallel was specified in the engine args.\n            if self.distributed_executor_backend == \"external_launcher\":\n                # For external launcher,\n                # we need to set the data parallel rank automatically\n                self.data_parallel_rank = int(os.environ[\"RANK\"]) // (\n                    self.world_size // self.data_parallel_size\n                )\n                logger.info(\n                    \"Set data_parallel_rank to %d automatically.\",\n                    self.data_parallel_rank,\n                )\n            if not self.enable_elastic_ep:","sourceCodeStart":843,"sourceCodeEnd":879,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L843-L879","documentation":"Elastic EP with asynchronous EPLB (eplb_config.use_async=true) transfers expert states with NIXL. ParallelConfig lazily imports vllm.distributed.nixl_utils.is_nixl_available and raises when the NIXL package is absent from the environment.","triggerScenarios":"Running --enable-elastic-ep with an eplb config where use_async is true (its default in EPLBConfig) in a vLLM install built without NIXL support.","commonSituations":"Custom or older vLLM builds, slim Docker images that excluded NIXL, or CUDA environments where the nixl wheel was not installed; the error surfaces only when elastic EP + async EPLB are both requested.","solutions":["Install/build vLLM with NIXL support (e.g. a recent wheel that bundles nixl, or install the nixl package into the environment).","Or set --eplb-config.use_async=false to use synchronous EPLB rebalancing that does not need NIXL.","Verify with `python -c \"from vllm.distributed.nixl_utils import is_nixl_available; print(is_nixl_available())\"` before launching."],"exampleFix":"# before\nvllm serve model --enable-eplb --enable-elastic-ep --eplb-config '{\"use_async\": true}'\n# after (no NIXL available)\nvllm serve model --enable-eplb --enable-elastic-ep --eplb-config '{\"use_async\": false}'","handlingStrategy":"validation","validationCode":"def async_eplb_nixl_ok(use_async: bool) -> bool:\n    if not use_async:\n        return True\n    from vllm.distributed.nixl_utils import is_nixl_available\n    return is_nixl_available()","typeGuard":null,"tryCatchPattern":"try:\n    EngineArgs(enable_eplb=True, enable_elastic_ep=True,\n               eplb_config={\"use_async\": True})\nexcept ValueError as e:\n    if \"NIXL\" in str(e):\n        # fall back to sync EPLB rather than failing the deployment\n        EngineArgs(enable_eplb=True, enable_elastic_ep=True,\n                   eplb_config={\"use_async\": False})\n    else:\n        raise","preventionTips":["Run is_nixl_available() as a preflight check in elastic-EP deployments.","Pin a vLLM build that bundles NIXL, or add a container health check that imports nixl before startup."],"tags":["elastic-ep","eplb","nixl","dependencies","configuration"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}