sgl-project/sglang · error · ValueError

Invalid join mode: {mode}

Error message

Invalid join mode: {mode}

What it means

Raised by the forked-state collection's join() when `mode` is not one of the supported join modes ('concate_and_append' for KV-cache concatenation, and the string-concat mode handled above). It guards against silently discarding forked branches due to a typo'd mode name.

Source

Thrown at python/sglang/lang/interpreter.py:1073

            src_vars = self.src_state.stream_executor.variables
            src_var_set = set(src_vars.keys())
            for child_state in self.states:
                child_state.stream_executor.sync()
                child_vars = child_state.stream_executor.variables
                new_vars = set(child_vars.keys()) - src_var_set

                for k in new_vars:
                    if k in src_vars:
                        src_vars[k].append(child_vars[k])
                    else:
                        src_vars[k] = [child_vars[k]]
        elif mode == "concate_and_append":
            # Concatenate and append KV cache
            self.src_state += SglConcateAndAppend(self.states)
            # Need a sync here. Otherwise, `states` can be deleted.
            self.src_state.stream_executor.sync()
        else:
            raise ValueError(f"Invalid join mode: {mode}")

        for s in self.states:
            s.stream_executor.end()

    def __getitem__(self, i: int):
        return self.states[i]

    def __setitem__(self, i: int, value):
        assert self.states[i] == value

    def __iadd__(self, other):
        if isinstance(other, Callable):
            # lambda function
            for i in range(len(self.states)):
                self.states[i] += other(i)
        elif isinstance(other, SglExpr):
            for i in range(len(self.states)):
                self.states[i] += other

View on GitHub (pinned to 0132848349)

Solutions

1. Use exactly the supported mode strings, e.g. mode="concate_and_append" for KV-cache join
2. Check the installed sglang version's interpreter.py for the accepted modes
3. Validate mode against an allowlist before calling join

Example fix

# before
joined = forked.join(mode="concat_and_append")
# after
joined = forked.join(mode="concate_and_append")

VALID_JOIN_MODES = {"concate_and_append", "variable_append"}  # check your version's interpreter.py
if mode not in VALID_JOIN_MODES:
    raise ValueError(f"mode must be one of {VALID_JOIN_MODES}")
joined = forked.join(mode=mode)

def is_join_mode(m: str) -> bool:
    return isinstance(m, str) and m in {"concate_and_append", "variable_append"}

try:
    joined = forked.join(mode=mode)
except ValueError as e:
    if "Invalid join mode" in str(e):
        joined = forked.join(mode="concate_and_append")
    else:
        raise

When it happens

Trigger: Calling states.join(mode="concat") or any misspelling/unsupported mode; passing a mode string introduced in a different sglang version.

Common situations: Typos like 'concatenate_and_append' vs 'concate_and_append'; code written against newer API run on older sglang; programmatic mode selection with unvalidated input.

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

• Unknown type: {type(other)}
• Tried to append None to state.
• Invalid value: {other}
• invalid CUDA handle-type value: {handle_type_value}
• v_cache must be provided

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