sgl-project/sglang · error · ValueError

extra_key should be a list or a string.

Error message

extra_key should be a list or a string.

What it means

Raised when extra_key is neither a str nor a list. _normalize_extra_key only supports a single string (broadcast to all requests) or a per-request list of strings; any other type (int, dict, tuple) is rejected.

Source

Thrown at python/sglang/srt/managers/io_struct.py:797

    def _normalize_extra_key(self, num):
        """Normalize extra_key for batch processing."""
        if self.extra_key is None:
            return
        if isinstance(self.extra_key, str):
            value = self.extra_key or None
            self.extra_key = [value] * num
        elif isinstance(self.extra_key, list):
            if len(self.extra_key) != self.batch_size:
                raise ValueError(
                    "The length of extra_key should be equal to the batch size."
                )
            if any(not isinstance(value, str) for value in self.extra_key):
                raise ValueError("Every extra_key should be a string.")
            self.extra_key = [value or None for value in self.extra_key]
            self.extra_key = self.extra_key * self.parallel_sample_num
        else:
            raise ValueError("extra_key should be a list or a string.")

    def _normalize_cache_salt(self, num):
        """Normalize cache_salt for batch processing."""
        if self.cache_salt is None:
            return
        if isinstance(self.cache_salt, str):
            value = self.cache_salt or None
            self.cache_salt = [value] * num
        elif isinstance(self.cache_salt, list):
            if len(self.cache_salt) != self.batch_size:
                raise ValueError(
                    "The length of cache_salt should be equal to the batch size."
                )
            if any(not isinstance(value, str) for value in self.cache_salt):
                raise ValueError("Every cache_salt should be a string.")
            self.cache_salt = [value or None for value in self.cache_salt]
            self.cache_salt = self.cache_salt * self.parallel_sample_num
        else:

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a single str to use the same key for the whole batch
2. Pass a list[str] with len == batch_size

Example fix

// before
extra_key=12345
// after
extra_key='12345'

if not isinstance(extra_key, (str, list)):
    extra_key = str(extra_key)

def valid_extra_key(k): return k is None or isinstance(k, (str, list))

When it happens

Trigger: GenerateReqInput(..., extra_key=123) or extra_key={'k':'v'} or a tuple of keys.

Common situations: Passing a numeric hash or dict-shaped cache key; refactor changed extra_key from flexible type to str/list only.

Related errors

• Every extra_key should be a string.
• Every cache_salt should be a string.
• Unsupported image type: {type(image)}
• MiniMax H3 model variant must be a non-empty string
• Hunyuan3D expects image_path as str, got {type(batch.image_p

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