[Feature]: Warn or auto-convert to FlexibleArgumentParser in AsyncEngineArgs.add_cli_args #19221
Description
🚀 The feature, motivation and pitch
When using AsyncEngineArgs.add_cli_args, the error messages do not make it obvious that issues may be caused by the type of parser provided—particularly when it is not a FlexibleArgumentParser. This can lead to confusion during debugging, especially for users upgrading to newer versions of vllm.
To improve developer experience, I propose the following enhancement:
• AsyncEngineArgs.add_cli_args should raise a warning if the provided parser is not a FlexibleArgumentParser.
• If feasible, it should automatically wrap or convert the parser into a FlexibleArgumentParser.
This change would provide immediate and actionable feedback to users, helping them avoid subtle bugs caused by incorrect parser types(I know that modern day editors and typecheckers should be able to spot this). It would also reduce friction when upgrading across versions of vllm, particularly from versions prior to v0.9.
Alternatives
No response
Additional context
I noticed an update in vllm==0.9 about integrating the deprecated option support in FlexibleArgumentParser. See PR #17426 for related changes.
This update caused an error in my existing code that looked like this:
parser = argparse.ArgumentParser()
parser.add_argument("--host", type=str, default="0.0.0.0")
parser.add_argument("--port", type=int, default=5000)
parser.add_argument("--ssl-keyfile", type=str, default=None)
parser.add_argument("--ssl-certfile", type=str, default=None)
parser.add_argument(
"--root-path",
type=str,
default=None,
help="FastAPI root_path when app is behind a path-based routing proxy")
parser = AsyncEngineArgs.add_cli_args(parser)
args = parser.parse_args()
engine_args = AsyncEngineArgs.from_cli_args(args)
engine = AsyncLLMEngine.from_engine_args(engine_args)
It threw this error:
File "/home/aiscuser/.conda/envs/ruler/lib/python3.10/argparse.py", line 1430, in add_argument
action = action_class(**kwargs)
TypeError: _StoreAction.__init__() got an unexpected keyword argument 'deprecated'
The root cause: I was incorrectly using argparse.ArgumentParser instead of FlexibleArgumentParser. This was a longstanding mistake in my code, inherited from a snippet in NVIDIA/RULER (a well-used repo with 1.2k+ stars). The code had been working fine in earlier versions of vllm, but broke after upgrading to v0.9.
What changed in vllm==0.9 is that FlexibleArgumentParser began overriding the parse_known_args method to support Python's new deprecated argument feature (ahead of Python 3.13). Since ArgumentParser lacks this override, the same function fails with a TypeError due to the unrecognized deprecated argument.
Before submitting a new issue...
- Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.