sgl-project/sglang · error · ValueError

extra_config['spdk_passthrough'] must be a dict of spdk_* fi

Error message

extra_config['spdk_passthrough'] must be a dict of spdk_* field overrides

What it means

spdk_passthrough is an expert escape hatch forwarding raw spdk_* overrides to UMBPSsdConfig; it must be a dict mapping field names to values. Passing a string/list/None raises this ValueError.

Source

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

        if "spdk_proxy_idle_exit_timeout_ms" in extra:
            cfg.ssd.spdk_proxy_idle_exit_timeout_ms = int(
                extra["spdk_proxy_idle_exit_timeout_ms"]
            )
        if "spdk_proxy_allow_borrow" in extra:
            cfg.ssd.spdk_proxy_allow_borrow = _strict_bool(
                extra["spdk_proxy_allow_borrow"], "spdk_proxy_allow_borrow"
            )
        if "spdk_proxy_reserved_shared_bytes" in extra:
            cfg.ssd.spdk_proxy_reserved_shared_bytes = int(
                extra["spdk_proxy_reserved_shared_bytes"]
            )

        # Expert escape hatch for advanced SPDK knobs outside the stable
        # extra_config surface, forwarded to UMBPSsdConfig as-is.
        if "spdk_passthrough" in extra:
            overrides = extra["spdk_passthrough"]
            if not isinstance(overrides, dict):
                raise ValueError(
                    "extra_config['spdk_passthrough'] must be a dict of "
                    "spdk_* field overrides"
                )
            applied = []
            for field_name, field_value in overrides.items():
                if not field_name.startswith("spdk_") or not hasattr(
                    cfg.ssd, field_name
                ):
                    raise ValueError(
                        f"spdk_passthrough: unknown SSD config field {field_name!r} "
                        "(must be an existing spdk_* field on UMBPSsdConfig)"
                    )
                current = getattr(cfg.ssd, field_name)
                setattr(
                    cfg.ssd,
                    field_name,
                    _cast_like(current, field_value, field_name),
                )

View on GitHub (pinned to 0132848349)

Solutions

1. Pass an actual dict: {'spdk_passthrough': {'spdk_some_knob': value}}
2. If config comes from CLI JSON, ensure it is parsed into a dict before constructing the store

Example fix

# before
extra['spdk_passthrough'] = '{"spdk_io_queue_count": 4}'  # string!
# after
extra['spdk_passthrough'] = {'spdk_io_queue_count': 4}

if 'spdk_passthrough' in extra:
    assert isinstance(extra['spdk_passthrough'], dict), 'spdk_passthrough must be a dict'
    if isinstance(extra['spdk_passthrough'], str):
        extra['spdk_passthrough'] = json.loads(extra['spdk_passthrough'])

def is_spdk_passthrough_dict(v) -> bool:
    return isinstance(v, dict)

When it happens

Trigger: Setting extra_config['spdk_passthrough'] to a non-dict, e.g. a JSON string or a list of key=value pairs.

Common situations: Passing un-parsed JSON from the CLI (the extra config arrives as a str instead of a dict).

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• spdk_passthrough: unknown SSD config field {!r} (must be an
• extra_config[{!r}] must be a boolean-like value (true/false,
• {} must not be None
• {} must not be empty
• {} has {} entries, but rank_index={}

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