sgl-project/sglang · error · ValueError
kv-canary: kv_canary must be one of none/log/raise, got
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.
Solutions
- Use exactly one of: --kv-canary none, --kv-canary log, or --kv-canary raise
- Check spelling (common typo: 'rasie'); the parser is case-insensitive but exact-match on mode name
- 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
- Remember the exact vocabulary: none | log | raise (case-insensitive)
- Add argparse choices=['none','log','raise'] in wrapper scripts
- Double-check spelling (e.g. 'rasie') when copying commands
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
- Invalid attention backend
- Invalid backend: . Must be one of
- rollout_sde_type must be one of
- Unknown CacheAgnostic Policy
- Unknown CacheAware Policy
AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28).
Data as JSON: /api/errors/3024eeb0edb54b7a.
Report an issue: GitHub.
Appendix: 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)