sgl-project/sglang · error · ImportError

Please install mooncake by following the instructions at htt

Error message

Please install mooncake by following the instructions at https://kvcache-ai.github.io/Mooncake/getting_started/build.html to run SGLang with MooncakeConnector.

What it means

`from mooncake.store import MooncakeDistributedStore` raised ImportError, so the Mooncake transfer engine package is not installed in the Python environment. SGLang re-raises with install instructions and the docs URL, chaining the original ImportError.

Source

Thrown at python/sglang/srt/mem_cache/storage/mooncake_store/mooncake_store.py:274

            ),
            tenant_id=_normalize_tenant_id(
                extra_config.get("tenant_id", envs.MOONCAKE_TENANT_ID.default)
            ),
        )


class MooncakeBaseStore:
    def __init__(self):
        self.store = None
        self.config = None

    def _import_mooncake_store(self):
        try:
            from mooncake.store import MooncakeDistributedStore

            return MooncakeDistributedStore
        except ImportError as e:
            raise ImportError(
                "Please install mooncake by following the instructions at "
                "https://kvcache-ai.github.io/Mooncake/getting_started/build.html "
                "to run SGLang with MooncakeConnector."
            ) from e

    def _import_mooncake_group_semantics(self):
        try:
            from mooncake.store import ReplicateConfig
        except ImportError:
            return None, False

        supports_group_ids = hasattr(ReplicateConfig, "group_ids")
        if not supports_group_ids:
            try:
                supports_group_ids = hasattr(ReplicateConfig(), "group_ids")
            except Exception:
                supports_group_ids = False
        return ReplicateConfig, supports_group_ids

View on GitHub (pinned to 0132848349)

Solutions

1. pip install mooncake-transfer-engine (or build per the linked Mooncake docs)
2. Or disable the mooncake backend (use file backing) until installed

Example fix

# before
OSError/ImportError ... MooncakeConnector
# after
pip install mooncake-transfer-engine --upgrade
python -m sglang.launch_server --hicache-storage-backend mooncake ...

def mooncake_available() -> bool:
    try:
        from mooncake.store import MooncakeDistributedStore  # noqa
        return True
    except ImportError:
        return False
assert mooncake_available(), 'pip install mooncake-transfer-engine'

def mooncake_available() -> bool:
    try:
        from mooncake.store import MooncakeDistributedStore  # noqa
        return True
    except ImportError:
        return False

try:
    from sglang.srt.mem_cache.storage.mooncake_store.mooncake_store import MooncakeStore
except ImportError as e:
    if 'install mooncake' in str(e):
        raise SystemExit('Install mooncake-transfer-engine or use a non-mooncake backend')
    raise

When it happens

Trigger: Using MooncakeConnector/MooncakeStore (e.g. --hicache-storage-backend mooncake) in an environment without mooncakestore/mooncake-transfer-engine installed.

Common situations: Default SGLang install (mooncake optional); new venv; broken wheel install leaving a partial module.

Related errors

• Sparse Video Gen 2 attention backend requires svg package to
• Humming quantization requires `humming-kernels`. Please inst
• hf3fs_fuse.io is not available. Please install the hf3fs_fus
• LMCache is not installed. Please install it by running `pip
• The fastokens package is required when --tokenizer-backend=f

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