sgl-project/sglang · error · KeyError

unknown Inkling special token: {token!r}

Error message

unknown Inkling special token: {token!r}

What it means

normalize_special_token only accepts known Inkling special tokens, in either the bare ('message_user') or angle-bracket ('<|message_user|>') spelling. Anything else raises KeyError with the offending token repr.

Source

Thrown at python/sglang/srt/parser/inkling_tokenizer.py:80

    for token in INKLING_SPECIAL_TOKENS
}

ROLE_MESSAGE_TOKENS: dict[str, str] = {
    "user": MESSAGE_USER,
    "assistant": MESSAGE_MODEL,
    "system": MESSAGE_SYSTEM,
    "tool": MESSAGE_TOOL,
}


def normalize_special_token(token: str) -> str:
    """Accept either message_user or <|message_user|> spellings."""
    if token in INKLING_SPECIAL_TOKENS:
        return token
    try:
        return INKLING_SPECIAL_TOKEN_NAMES[token]
    except KeyError as exc:
        raise KeyError(f"unknown Inkling special token: {token!r}") from exc


@dataclass(frozen=True)
class InklingTokenizer:
    """Small wrapper around a base text tokenizer plus Inkling framing IDs.

    Plain text is encoded by the base tokenizer, while the minimal chat
    framing tokens are inserted from the fixed overlay map.
    """

    tokenizer: Any
    special_token_ids: Mapping[str, int] | None = None

    def encode_text(self, text: str) -> list[int]:
        if not isinstance(text, str):
            raise TypeError(f"text must be str, got {type(text).__name__}")
        return list(self.tokenizer.encode(text, add_special_tokens=False))

View on GitHub (pinned to 0132848349)

Solutions

1. Check the exact spelling against INKLING_SPECIAL_TOKENS defined in the same module
2. Use the bare name form first ('message_user'); fall back to the '<|message_user|>' form
3. Don't pass regular text through encode_special — use encode_text for that

Example fix

// before
ids = tok.encode_special("<|msg_user|>")
// after
ids = tok.encode_special("message_user")

from sglang.srt.parser.inkling_tokenizer import INKLING_SPECIAL_TOKENS

def safe_encode_special(tok, token):
    if token not in INKLING_SPECIAL_TOKENS:
        raise ValueError(f"bad token {token!r}; valid: {sorted(INKLING_SPECIAL_TOKENS)}")
    return tok.encode_special(token)

def is_inkling_special(token: str) -> TypeGuard[str]:
    from sglang.srt.parser.inkling_tokenizer import INKLING_SPECIAL_TOKENS
    return token in INKLING_SPECIAL_TOKENS or token.strip("<|>") in INKLING_SPECIAL_TOKENS

try:
    tid = tok.encode_special(token)
except KeyError as e:
    logger.warning("skipping unknown special token %s", token)
    tid = None

When it happens

Trigger: Calling encode_special('message_assistant_typo') or encode_special('<|unknown_token|>') — any token not present in INKLING_SPECIAL_TOKENS / INKLING_SPECIAL_TOKEN_NAMES.

Common situations: Typos in token names, version drift where newer/older token sets differ, or passing ordinary text instead of a special token name.

Related errors

• text must be str, got {type(text).__name__}
• MXFP8 fused prologue requires head_dim-aligned Q/K/V.
• MXFP8 fused prologue requires K/V scale buffers.
• MXFP8 fused prologue requires interleaved K/V scale buffers
• MXFP8 fused prologue requires contiguous interleaved SFK/SFV

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