sgl-project/sglang · error · ValueError

--default-chat-template-kwargs must decode to a JSON object

Error message

--default-chat-template-kwargs must decode to a JSON object

What it means

Raised by _handle_other_validations when --default-chat-template-kwargs was parsed but did not decode to a JSON object (dict). The value must be a JSON mapping of kwargs passed to the chat template renderer; arrays, strings, or scalars are rejected.

Source

Thrown at python/sglang/srt/server_args.py:9574

                f"(got {cfg.asr_max_buffer_seconds})."
            )
        if cfg.asr_max_concurrent_sessions <= 0:
            raise ValueError(
                f"--asr-max-concurrent-sessions must be positive "
                f"(got {cfg.asr_max_concurrent_sessions})."
            )

    def _validate_prefill_decode_interval(self):
        cfg = resolving_view(self)
        if cfg.prefill_decode_interval < 0:
            raise ValueError("--prefill-decode-interval must be non-negative.")

    def _handle_other_validations(self):
        cfg = resolving_view(self)
        if cfg.default_chat_template_kwargs is not None and not isinstance(
            cfg.default_chat_template_kwargs, dict
        ):
            raise ValueError(
                "--default-chat-template-kwargs must decode to a JSON object"
            )

        # Handle optimistic prefill validation
        if cfg.optimistic_prefill_attempts > 0 and cfg.disaggregation_mode == "prefill":
            if cfg.pp_size > 1:
                logger.warning("Optimistic prefill does not support pp_size > 1")
                self._declare(
                    "_handle_other_validations",
                    optimistic_prefill_attempts=0,
                )
            elif cfg.enable_hierarchical_cache and (
                cfg.hicache_storage_backend is not None
                or cfg.hicache_write_policy != "write_back"
            ):
                logger.warning(
                    "Optimistic prefill only supports L2 hierarchical cache "
                    "with write-back policy"

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the value is a JSON object: --default-chat-template-kwargs '{"enable_thinking": false}'
2. Verify shell quoting preserves the braces
3. If loading programmatically, json.loads the value and check isinstance(dict) before launch

Example fix

# before
--default-chat-template-kwargs "true"
# after
--default-chat-template-kwargs '{"enable_thinking": false}'

import json
if args.default_chat_template_kwargs is not None:
    v = args.default_chat_template_kwargs
    if isinstance(v, str):
        v = json.loads(v)
    assert isinstance(v, dict), 'default_chat_template_kwargs must be a JSON object'

def is_valid_template_kwargs(v) -> bool:
    import json
    if isinstance(v, str):
        try: v = json.loads(v)
        except Exception: return False
    return isinstance(v, dict)

except ValueError as e:
    if 'default-chat-template-kwargs' in str(e):
        fix quoting / re-pass as a JSON object

When it happens

Trigger: Passing --default-chat-template-kwargs '[1,2]' or '"text"' or other non-object JSON; also when a config loader mis-parses the string into a non-dict.

Common situations: Forgetting braces around the JSON; quoting issues in shell causing partial parse; passing a template string instead of kwargs.

Related errors

• Assistant tool call function.arguments must be valid JSON.
• Assistant tool call function.arguments must be a JSON object
• Decode context parallel size (--dcp-size / --decode-context-
• --mamba-max-states-per-path must be -1 (unlimited) or a posi
• --swa-full-tokens-ratio should be in range (0, 1.0].

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