[Pooling UX] Improve serve --task error guidance (#53467)
Signed-off-by: Taneem Ibrahim <taneem.ibrahim@gmail.com>
Taneem Ibrahim committed
Aug 25, 2026 at 08:20 UTC
2014e4748502d5526fd515d2289a87d046e717a1
1 file changed
+20
-1
vllm/utils/argparse_utils.py
+20
-1
@@ -16,7 +16,7 @@ from argparse import (
16
_ArgumentGroup,
17
)
18
from collections import defaultdict
19
-from typing import Any
19
+from typing import Any, NoReturn
20
21
import regex as re
22
import yaml
@@ -132,6 +132,22 @@ class FlexibleArgumentParser(ArgumentParser):
132
# Pop kwarg "add_json_tip" to control whether to add the JSON tip
133
self.add_json_tip = kwargs.pop("add_json_tip", True)
134
super().__init__(*args, **kwargs)
135
+ self._show_serve_task_hint = False
136
+
137
+ def error(self, message: str) -> NoReturn:
138
+ if (
139
+ (self.prog.endswith(" serve") or self._show_serve_task_hint)
140
+ and message.startswith("unrecognized arguments:")
141
+ and re.search(r"(^|\s)--task(=|\s|$)", message)
142
+ ):
143
+ message += (
144
+ "\n\nHint: --task is not a vllm serve option. "
145
+ "For embedding, reranking, or reward models, use "
146
+ "--runner pooling. To adapt a generative model for pooling, "
147
+ "also use --convert embed, --convert classify, or "
148
+ "--convert reward."
149
+ )
150
+ super().error(message)
151
152
if sys.version_info < (3, 13):
153
# Enable the deprecated kwarg for Python 3.12 and below
@@ -247,6 +263,9 @@ class FlexibleArgumentParser(ArgumentParser):
263
):
264
if args is None:
265
args = sys.argv[1:]
266
+ self._show_serve_task_hint = args[:1] == ["serve"] and any(
267
+ re.match(r"^--task(=.+|$)", arg) for arg in args[1:]
268
+ )
269
270
if args and args[0] == "serve":
271
# Check for --model in command line arguments first