sgl-project/sglang · error · ValueError

Unknown mode {mode!r}

Error message

Unknown mode {mode!r}

What it means

_register_forward_hook_or_replace_fn supports a fixed set of modes (forward pre-hook, post-hook, or forward replacement) selected by the mode argument in the DumpConfig. An unrecognized mode string falls through the if/elif chain to this ValueError.

Source

Thrown at python/sglang/srt/debug_utils/dumper.py:814

        original_forward = module.forward

        @functools.wraps(original_forward)
        def _wrapped(*args, **kwargs):
            pre_hook(module, args, kwargs)
            output = original_forward(*args, **kwargs)
            hook(module, args, output)
            return output

        module.forward = _wrapped

        class _Handle:
            def remove(self) -> None:
                assert module.forward is _wrapped
                module.forward = original_forward

        return [_Handle()]
    else:
        raise ValueError(f"Unknown mode {mode!r}")


# -------------------------------------- grafter ------------------------------------------


class _GraftRole(enum.Enum):
    BASELINE = "baseline"
    TARGET = "target"


class _GraftDirection(enum.Enum):
    B2T = "b2t"  # name flows baseline -> target
    T2B = "t2b"  # name flows target -> baseline


@dataclass
class GraftTransformInput:
    """Single argument passed to a user-supplied transform function.

View on GitHub (pinned to 0132848349)

Solutions

1. Check the mode branch labels in _register_forward_hook_or_replace_fn and use one of the exact strings
2. Use the config dataclass default or a documented constant instead of a raw string
3. After upgrading sglang, re-check valid mode names — they may have been renamed

Example fix

# before
cfg = HookConfig(mode="replce")
# after
cfg = HookConfig(mode="replace")  # use exact mode string from source

VALID_MODES = {"pre", "post", "replace"}  # mirror the source branches
assert cfg.mode in VALID_MODES, f"mode must be one of {VALID_MODES}"

try:
    dumper = Dumper(cfg)
except ValueError as e:
    if "Unknown mode" in str(e):
        print("valid modes:", VALID_MODES); raise

When it happens

Trigger: Constructing the dumper with a config whose mode is misspelled or from a newer/older version (e.g. 'replace_fn' vs 'replace', 'pre_hook' vs 'pre-hook'); __init__ passes cfg.mode straight through, so bad values surface at construction.

Common situations: Typos in the mode string, version skew between the config schema and installed sglang, hand-built config dicts.

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 config pair (missing '='): {pair!r}
• This browser cannot encode H.264 MP4
• H.264 encoder did not return MP4 decoder config
• This browser does not support gzip stream decoding
• delta payload size mismatch: expected ${expectedSize}, got $

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