sgl-project/sglang · error · ValueError

spdk_passthrough: unknown SSD config field {!r} (must be an

Error message

spdk_passthrough: unknown SSD config field {!r} (must be an existing spdk_* field on UMBPSsdConfig)

What it means

A key in the spdk_passthrough dict is rejected because it either doesn't start with 'spdk_' or doesn't exist as an attribute on cfg.ssd (UMBPSsdConfig). Only existing spdk_* fields can be overridden.

Source

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

            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),
                )
                applied.append(field_name)
            if applied:
                logger.warning(
                    "UMBPStore: using spdk_passthrough expert escape hatch for "
                    "fields %s; these are advanced backend knobs forwarded directly "
                    "to UMBPSsdConfig and are not part of the stable extra_config "
                    "surface.",
                    applied,
                )

View on GitHub (pinned to 0132848349)

Solutions

1. Prefix the key with spdk_ and confirm the field exists on UMBPSsdConfig (inspect cfg.ssd attributes)
2. Upgrade/align the mori version if the field is genuinely new
3. Prefer the documented stable extra_config keys when available

Example fix

# before
extra['spdk_passthrough'] = {'io_queue_count': 4}
# after
extra['spdk_passthrough'] = {'spdk_io_queue_count': 4}

VALID = {f for f in dir(cfg.ssd) if f.startswith('spdk_')}
assert all(k.startswith('spdk_') and k in VALID for k in extra['spdk_passthrough'])

def valid_spdk_fields(cfg, overrides) -> list:
    valid = {f for f in dir(cfg.ssd) if f.startswith('spdk_')}
    return [k for k in overrides if k not in valid]  # empty == ok

When it happens

Trigger: Passing {'io_queue_count': 4} (missing prefix) or {'spdk_future_field': 1} (not on UMBPSsdConfig in this mori version).

Common situations: Copying SPDK knob names from newer/older mori docs than the installed build; dropping the spdk_ prefix.

Related errors

• extra_config['spdk_passthrough'] must be a dict of spdk_* fi
• 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/c32289033b1ece87. Report an issue: GitHub.