sgl-project/sglang · error · ValueError

extra_config['ssd_backend'] must be one of: file, spdk, spdk

Error message

extra_config['ssd_backend'] must be one of: file, spdk, spdk_proxy

What it means

extra_config['ssd_backend'] selects the SSD implementation and must be 'file', 'spdk', or 'spdk_proxy'; other values are rejected in the UMBP store constructor.

Source

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

                    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:
                    cfg.ssd.durability.mode = UMBPDurabilityMode.Relaxed
        if "ssd_backend" in extra:
            ssd_backend = str(extra["ssd_backend"]).strip().lower()
            if ssd_backend not in ("file", "spdk", "spdk_proxy"):
                raise ValueError(
                    "extra_config['ssd_backend'] must be one of: "
                    "file, spdk, spdk_proxy"
                )
            cfg.ssd.ssd_backend = ssd_backend
        if "spdk_nvme_pci_addr" in extra:
            cfg.ssd.spdk_nvme_pci_addr = str(extra["spdk_nvme_pci_addr"])
        if "spdk_proxy_shm_name" in extra:
            cfg.ssd.spdk_proxy_shm_name = str(extra["spdk_proxy_shm_name"])
        if "spdk_proxy_startup_timeout_ms" in extra:
            cfg.ssd.spdk_proxy_startup_timeout_ms = int(
                extra["spdk_proxy_startup_timeout_ms"]
            )
        if "spdk_proxy_bin" in extra:
            cfg.ssd.spdk_proxy_bin = str(extra["spdk_proxy_bin"])
        if "spdk_proxy_tenant_id" in extra:
            cfg.ssd.spdk_proxy_tenant_id = int(extra["spdk_proxy_tenant_id"])
        if "spdk_proxy_tenant_quota_bytes" in extra:
            cfg.ssd.spdk_proxy_tenant_quota_bytes = int(

View on GitHub (pinned to 0132848349)

Solutions

1. Set ssd_backend to file, spdk, or spdk_proxy (use underscores)
2. If you meant the IO engine, use ssd_io_backend with posix/io_uring instead

Example fix

# before
extra['ssd_backend'] = 'io_uring'
# after
extra['ssd_backend'] = 'file'
extra['ssd_io_backend'] = 'io_uring'

assert str(extra.get('ssd_backend','')).strip().lower() in ('file','spdk','spdk_proxy')

def is_valid_ssd_backend(v) -> bool:
    return isinstance(v, str) and v.strip().lower() in ('file','spdk','spdk_proxy')

When it happens

Trigger: Setting ssd_backend to 'aio', 'io_uring', or a typo like 'spdk-proxy' (underscore required).

Common situations: Confusing ssd_backend (implementation) with ssd_io_backend (IO engine) and using the wrong vocabulary in one of them.

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_io_backend'] must be one of: posix, io_uri

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