sgl-project/sglang · error · ValueError

extra_config['ssd_io_backend'] must be one of: posix, io_uri

Error message

extra_config['ssd_io_backend'] must be one of: posix, io_uring

What it means

extra_config['ssd_io_backend'] only accepts 'posix' or 'io_uring' (case-insensitive, trimmed); anything else is rejected before the UMBPIoBackend enum is set.

Source

Thrown at python/sglang/srt/mem_cache/storage/umbp/umbp_store.py:340

            cfg.ssd.segment_size_bytes = int(extra["ssd_segment_size_bytes"])
        if "ssd_copy_batch_max_ops" in extra:
            cfg.copy_pipeline.batch_max_ops = int(extra["ssd_copy_batch_max_ops"])
        if "ssd_queue_depth" in extra:
            cfg.ssd.io.queue_depth = int(extra["ssd_queue_depth"])
        if "ssd_copy_worker_threads" in extra:
            cfg.copy_pipeline.worker_threads = int(extra["ssd_copy_worker_threads"])
        if "auto_promote_on_read" in extra:
            cfg.eviction.auto_promote_on_read = _strict_bool(
                extra["auto_promote_on_read"], "auto_promote_on_read"
            )
        if "eviction_policy" in extra:
            cfg.eviction.policy = str(extra["eviction_policy"])
        if "eviction_candidate_window" in extra:
            cfg.eviction.candidate_window = int(extra["eviction_candidate_window"])
        if "ssd_io_backend" in extra:
            backend = str(extra["ssd_io_backend"]).strip().lower()
            if backend not in ("posix", "io_uring"):
                raise ValueError(
                    "extra_config['ssd_io_backend'] must be one of: posix, io_uring"
                )
            if UMBPIoBackend is not None:
                cfg.ssd.io.backend = (
                    UMBPIoBackend.Posix if backend == "posix" else UMBPIoBackend.IoUring
                )
        if "ssd_durability_mode" in extra:
            # Validate even when the enum is unavailable (older mori / mocks).
            durability = str(extra["ssd_durability_mode"]).strip().lower()
            if durability not in ("strict", "sync", "relaxed", "async"):
                raise ValueError(
                    "extra_config['ssd_durability_mode'] must be one of: "
                    "strict, sync, relaxed, async"
                )
            if UMBPDurabilityMode is not None:
                if durability in ("strict", "sync"):
                    cfg.ssd.durability.mode = UMBPDurabilityMode.Strict
                else:

View on GitHub (pinned to 0132848349)

Solutions

1. Use 'posix' or 'io_uring' exactly (case-insensitive)
2. Confirm io_uring support in the kernel/mori build if selecting io_uring

Example fix

# before
extra['ssd_io_backend'] = 'aio'
# after
extra['ssd_io_backend'] = 'io_uring'

assert str(extra.get('ssd_io_backend','')).strip().lower() in ('posix','io_uring')

def is_valid_io_backend(v) -> bool:
    return isinstance(v, str) and v.strip().lower() in ('posix', 'io_uring')

When it happens

Trigger: Setting ssd_io_backend to 'libaio', 'aio', 'uring' or a typo'd string in the UMBP store extra_config.

Common situations: Porting config from another storage engine with different backend names; typo 'io_uring' vs 'iouring'.

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

• extra_config[{!r}] must be a boolean-like value (true/false,
• {} must not be None
• {} must not be empty
• {} has {} entries, but rank_index={}
• extra_config['ssd_durability_mode'] must be one of: strict,

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