sgl-project/sglang · error · ValueError

Invalid modality string: {modality_str}. Valid modalities ar

Error message

Invalid modality string: {modality_str}. Valid modalities are: {[m.name for m in Modality]}

What it means

Modality.from_str converts a modality name to the Modality enum via Modality[name.upper()]; unknown names raise ValueError listing valid options (IMAGE, VIDEO, AUDIO, and any other enum members).

Source

Thrown at python/sglang/srt/managers/schedule_batch.py:315

        return {
            "type": "abort",
            "message": self.message,
            "status_code": self.status_code,
            "err_type": self.err_type,
        }


class Modality(Enum):
    IMAGE = auto()
    VIDEO = auto()
    AUDIO = auto()

    @staticmethod
    def from_str(modality_str: str):
        try:
            return Modality[modality_str.upper()]
        except KeyError:
            raise ValueError(
                f"Invalid modality string: {modality_str}. Valid modalities are: {[m.name for m in Modality]}"
            )

    @staticmethod
    def all():
        return [Modality.IMAGE, Modality.VIDEO, Modality.AUDIO]


class MultimodalInputFormat(Enum):
    NORMAL = auto()
    PROCESSOR_OUTPUT = auto()
    PRECOMPUTED_EMBEDDING = auto()


# Msgpack-native containers and Ext-decoded tensor/transport leaves. Tuple
# containers intentionally decode as lists, matching msgpack's native model.
MultimodalDataValue: TypeAlias = object

View on GitHub (pinned to 0132848349)

Solutions

1. Send exact enum names case-insensitively: 'image', 'video', 'audio'
2. Strip/normalize input: from_str(s.strip().lower()) compatible spellings
3. Catch ValueError and return a 400 with the valid list

Example fix

# before
mod = Modality.from_str('img')
# after
mod = Modality.from_str('image')

VALID = {m.name.lower() for m in Modality}
modality_str = modality_str.strip().lower()
assert modality_str in VALID, f'invalid modality {modality_str}'

def is_valid_modality(s): return isinstance(s, str) and s.strip().upper() in Modality.__members__

try:
    mod = Modality.from_str(s)
except ValueError:
    return json_error(400, f'invalid modality: {s}; valid: image, video, audio')

When it happens

Trigger: Modality.from_str('image ') (whitespace), 'img', 'text', or a typo like 'vido' — usually from parsing a user-supplied modality field in an API or config.

Common situations: REST/schema fields accepting free-form modality strings; frontend sending abbreviations ('img','aud').

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid modality: {modality}
• return_hidden_states must be a boolean or the string literal
• Unknown serve backend {name!r}. Available values: {available
• Multiple distributions register serve backend {name!r}: {pro
• Failed to load serve backend {name!r} from {self._entry_poin

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