sgl-project/sglang · error · ValueError

expert-pack direct I/O is unavailable on this platform

Error message

expert-pack direct I/O is unavailable on this platform

What it means

ExpertPackStore was configured with direct_io=True, but the platform's os module lacks O_DIRECT (e.g. macOS or Windows). Direct I/O is only available on Linux, and the store fails fast rather than silently falling back to buffered I/O with different performance characteristics.

Source

Thrown at python/sglang/srt/layers/moe/expert_pack.py:190

    store.cache_vram_reserve_mib = int(cache_vram_reserve_mib)
    store.kernel_backend = "custom"
    store.stage_slot_count = int(stage_slots)
    store.read_splits = int(read_splits)
    store.direct_io = bool(direct_io)
    store.stats_flush_interval = int(stats_flush_interval)
    if (
        store.cache_vram_mib <= 0
        or store.cache_vram_reserve_mib <= 0
        or store.stage_slot_count <= 0
        or store.read_splits <= 0
    ):
        raise ValueError(
            "expert cache and staging budgets, and read splits, must be positive"
        )
    if store.stats_flush_interval < 0:
        raise ValueError("expert-pack stats flush interval cannot be negative")
    if store.direct_io and not hasattr(os, "O_DIRECT"):
        raise ValueError("expert-pack direct I/O is unavailable on this platform")
    open_flags = os.O_RDONLY | (os.O_DIRECT if store.direct_io else 0)
    store._fd = os.open(store.path, open_flags)
    store._lock = threading.RLock()
    store._cache = None
    store._cache_slots = []
    store._key_to_slot = {}
    store._key_frequency = {}
    store._lru = OrderedDict()
    store._staging = []
    store._stage_events = []
    store._stage_cursor = 0
    store._transfer_stream = None
    store._read_executor = None
    store._active_keys = set()
    store._route_calls_by_layer = [0] * store.header.num_layers
    store._route_tokens_by_layer = [0] * store.header.num_layers
    store.stats_path = Path(stats_path).resolve() if stats_path else None
    store._last_stats_flush_calls = 0

View on GitHub (pinned to 0132848349)

Solutions

1. Set direct_io=False on non-Linux platforms
2. Gate the flag on platform: direct_io=(sys.platform == 'linux')
3. Keep the direct-I/O tuning only in the Linux deployment config

Example fix

# before
store = ExpertPackStore(p, direct_io=True)  # on macOS -> ValueError

# after
import sys
store = ExpertPackStore(p, direct_io=(sys.platform == "linux"))

import sys, os
direct_io = bool(direct_io) and sys.platform == "linux" and hasattr(os, "O_DIRECT")

When it happens

Trigger: Constructing ExpertPackStore(direct_io=True) on macOS or Windows where os.O_DIRECT does not exist; also some container/filesystem combos where the constant is unavailable.

Common situations: Developing on a Mac against packs produced for Linux servers; configs tuned for Linux deployed unchanged to other platforms; CIFS/FUSE mounts without O_DIRECT support in the build.

Related errors

• expert cache and staging budgets, and read splits, must be p
• expert-pack stats flush interval cannot be negative
• expert-pack header coverage is inconsistent
• expert-pack is not identity triplet layout
• expert-pack alignment is invalid

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