sgl-project/sglang · error · ValueError

kv-canary: kv_canary must be one of none/log/raise, got {mod

Error message

kv-canary: kv_canary must be one of none/log/raise, got {mode_raw!r}

What it means

CanaryConfig.from_env parses the --kv-canary CLI value (trimmed and lowercased) and only accepts the modes 'none', 'log', or 'raise'. Any other string raises ValueError with the offending value shown via repr.

Source

Thrown at python/sglang/srt/kv_canary/config.py:66

            ForwardBatch.init_new) and compare against the canary's stored tokens at verify time.
            Independent of ``enable_write_input_assert``.
        stats_print_every_n_steps: 0 disables periodic stats logging; positive N prints
            "canary protected N tokens, ran M sweep passes, K violations so far" every N forward steps.
    """

    mode: CanaryMode
    ring_capacity: int
    sweep_interval: int
    real_kv_hash_mode: RealKvHashMode
    enable_write_input_assert: bool
    enable_verify_token_assert: bool
    stats_print_every_n_steps: int

    @classmethod
    def from_env(cls, server_args: ServerArgs) -> CanaryConfig:
        mode_raw = server_args.kv_canary.strip().lower()
        if mode_raw not in ("none", "log", "raise"):
            raise ValueError(
                f"kv-canary: kv_canary must be one of none/log/raise, got {mode_raw!r}"
            )

        real_kv_raw = server_args.kv_canary_real_data.strip().upper()

        return cls(
            mode=CanaryMode(mode_raw),
            ring_capacity=envs.SGLANG_KV_CANARY_RING_CAPACITY.get(),
            sweep_interval=server_args.kv_canary_sweep_interval,
            real_kv_hash_mode=RealKvHashMode[real_kv_raw],
            enable_write_input_assert=envs.SGLANG_KV_CANARY_ENABLE_WRITE_INPUT_ASSERT.get(),
            enable_verify_token_assert=envs.SGLANG_KV_CANARY_ENABLE_VERIFY_TOKEN_ASSERT.get(),
            stats_print_every_n_steps=envs.SGLANG_KV_CANARY_STATS_PRINT_EVERY_N_STEPS.get(),
        )

View on GitHub (pinned to 0132848349)

Solutions

  1. Use exactly one of: --kv-canary none, --kv-canary log, or --kv-canary raise
  2. Check spelling (common typo: 'rasie'); the parser is case-insensitive but exact-match on mode name
  3. Omit the flag entirely if the default (none) is acceptable

Example fix

# before
--kv-canary warn

# after
--kv-canary log
Defensive patterns

Strategy: type-guard

Validate before calling

raw = server_args.kv_canary.strip().lower()
if raw not in ("none", "log", "raise"):
    raise SystemExit(f"--kv-canary must be none|log|raise, got {raw!r}")
cfg = CanaryConfig.from_env(server_args)

Type guard

def is_valid_canary_mode(v: str) -> bool:
    return isinstance(v, str) and v.strip().lower() in ("none", "log", "raise")

Try / catch

try:
    cfg = CanaryConfig.from_env(server_args)
except ValueError as e:
    if 'kv_canary must be one of' in str(e):
        print('--kv-canary accepts only none|log|raise'); raise SystemExit(2)
    raise

Prevention

When it happens

Trigger: Passing --kv-canary <anything-else> (e.g. 'off', 'warn', 'True', '1', or a typo like 'rasie'); the value is stripped and lowercased but still must equal one of the three exact mode names.

Common situations: Typos or wrong vocabulary on the command line; scripts porting from another tool where the flag accepts boolean-ish values; assuming any truthy string enables the canary.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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