sgl-project/sglang · error · SystemExit

error: unrecognized arguments: {' '.join(remaining)}

Error message

error: unrecognized arguments: {' '.join(remaining)}

What it means

SystemExit raised by ServerArgs.from_cli_args after CLI parsing and component-path/attention-backend extraction left unrecognized tokens in `remaining`. It is argparse-style strict validation: any argument that is not a known ServerArgs field (or one of the dynamic component extractors) aborts startup.

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:3033

        if unknown_args is None:
            unknown_args = []

        dynamic_quantizations, remaining = cls._extract_component_quantizations(
            unknown_args
        )
        dynamic_ignored_layers, remaining = (
            cls._extract_component_quantization_ignored_layers(remaining)
        )
        # Extract the more specific weights suffix before the generic path alias.
        dynamic_weights_paths, remaining = cls._extract_component_weights_paths(
            remaining
        )
        dynamic_paths, remaining = cls._extract_component_paths(remaining)
        dynamic_attention_backends, remaining = (
            cls._extract_component_attention_backends(remaining)
        )
        if remaining:
            raise SystemExit(f"error: unrecognized arguments: {' '.join(remaining)}")

        provided_args = cls.get_provided_args(args, unknown_args)
        explicit_arg_names = set(provided_args)

        # Handle config file
        config_file = provided_args.get("config")
        if config_file:
            config_args = cls.load_config_file(config_file)
            explicit_arg_names.update(config_args)
            provided_args = {**config_args, **provided_args}

        if default_args:
            for key, value in default_args.items():
                provided_args.setdefault(key, value)

        if dynamic_paths:
            existing = dict(provided_args.get("component_paths") or {})
            existing.update(dynamic_paths)

View on GitHub (pinned to 0132848349)

Solutions

1. Re-run with --help and compare the exact spelling of the offending argument named in the message.
2. Check the release notes / _reject_retired_args list for renamed arguments and update the command.
3. Fix shell quoting so each flag and its value form the expected tokens.
4. Remove the unsupported argument entirely if the feature no longer exists.

Example fix

# before
--model-path ... --tensore-paralle-size 2   # typo
# after
--model-path ... --tensor-parallel-size 2

import inspect, dataclasses
valid = {f.name for f in dataclasses.fields(ServerArgs)}
unknown = [a for a in my_flags if a.lstrip("-").replace("-", "_") not in valid]
assert not unknown, f"bad flags: {unknown}"

def is_valid_flag(flag: str) -> bool:
    name = flag.lstrip("-").replace("-", "_").split("=")[0]
    return name in {f.name for f in dataclasses.fields(ServerArgs)}

try:
    args = ServerArgs.from_cli_args(argv)
except SystemExit as e:
    log.error("CLI rejected: %s", e); raise

When it happens

Trigger: Passing a misspelled or removed flag (e.g. --tp-size vs --tp_size, or a flag retired in this version), passing a flag value in the wrong position so it is not consumed, or passing component args not handled by _extract_component_paths/_extract_component_attention_backends.

Common situations: Upgrading SGLang/multimodal_gen where an argument was renamed or deleted; copy-pasting a launch command from docs for a different version; typos in shell scripts; quoting bugs that split one arg into two tokens.

Related errors

• --diffusers-kwargs must be valid JSON. Got: {args.diffusers_
• Number of gpus must be positive
• Config file not found: {args.config}
• Config file not found: {args.config}
• The {option_string} option is not yet implemented

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/b87c4bc3b42e7f0c. Report an issue: GitHub.