sgl-project/sglang · error · ValueError

Unsupported config option '{key_norm}' with action '{action.

Error message

Unsupported config option '{key_norm}' with action '{action.__class__.__name__}'

What it means

Some argparse actions (e.g. custom store/append actions) cannot be represented in a YAML config, so the parser keeps a deny-list (unsupported_actions keyed by normalized key names). Any config key landing in that dict raises with the action class name. It fires before value-type dispatch (bool/list/dict/scalar).

Source

Thrown at python/sglang/srt/utils/server_args_config_parser.py:150

    def _validate_yaml_file(self, file_path: str) -> None:
        """Validate that the file is a YAML file."""
        path = Path(file_path)
        if path.suffix.lower() not in [".yaml", ".yml"]:
            raise ValueError(f"Config file must be YAML format, got: {path.suffix}")

        if not path.exists():
            raise ValueError(f"Config file not found: {file_path}")

    def _convert_config_to_args(self, config: Dict[str, Any]) -> List[str]:
        """Convert configuration dictionary to argument list."""
        args = []

        for key, value in config.items():
            key_norm = key.replace("-", "_")
            if key_norm in self.unsupported_actions:
                action = self.unsupported_actions[key_norm]
                msg = f"Unsupported config option '{key_norm}' with action '{action.__class__.__name__}'"
                raise ValueError(msg)
            if isinstance(value, bool):
                self._add_boolean_arg(args, key, value)
            elif isinstance(value, list):
                self._add_list_arg(args, key, value)
            elif isinstance(value, dict):
                self._add_scalar_arg(args, key, json.dumps(value))
            else:
                self._add_scalar_arg(args, key, value)

        return args

    def _add_boolean_arg(self, args: List[str], key: str, value: bool) -> None:
        """
        Add boolean argument to the list.

        Only store_true flags:
            - value True -> add flag
            - value False -> skip

View on GitHub (pinned to 0132848349)

Solutions

1. Remove the offending key from the YAML file and pass it as a CLI flag instead
2. Check the parser's unsupported_actions dict for the exact set of denied keys
3. Upgrade/downgrade sglang to a version where that option's action is supported in configs

Example fix

# before (config.yaml)
some-append-action: [a, b]
# after
# remove from config.yaml and pass on CLI:
python -m sglang.launch_server --config config.yaml --some-append-action a --some-append-action b

unsupported = parser.unsupported_actions  # normalized keys
bad = [k for k in config if k.replace("-", "_") in unsupported]
assert not bad, f"unsupported config keys: {bad}"

When it happens

Trigger: Including a denied key (with dashes normalized to underscores) in the YAML config whose argparse action class is in the parser's unsupported_actions mapping.

Common situations: Copying a full --help dump into YAML, including flags whose action type (e.g. special append or custom action classes) is unsupported in config form; version drift adding newly unsupported options.

Related errors

• Multiple config files specified! Only one allowed.
• Config file must contain a dictionary at root level
• Config file must be YAML format, got: {path.suffix}
• Config file not found: {file_path}
• {selection_error}{component_suffix}

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