sgl-project/sglang · error · ImportError

Failed to import 'set_transfer_engine' from 'mooncake.pg'. P

Error message

Failed to import 'set_transfer_engine' from 'mooncake.pg'. Please upgrade your 'mooncake-transfer-engine' installation to 0.3.11 or above.

What it means

When the elastic expert-parallel backend is set to 'mooncake' (--elastic-ep-backend mooncake), SGLang's shared-engine init imports set_transfer_engine from mooncake.pg to plug the TransferEngine into mooncake's process group. That helper only exists in mooncake-transfer-engine >= 0.3.11; on older installs the ImportError is re-raised with an upgrade instruction.

Source

Thrown at python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py:356

        )
        or get_exec().moe.elastic_ep_backend == "mooncake"
    )

    if use_mooncake_te:
        init_mooncake_transfer_engine(
            hostname=get_local_ip_auto(),
            gpu_id=gpu_id,
            ib_device=(
                get_disagg().disaggregation_ib_device
                or get_exec().moe.mooncake_ib_device
            ),
        )

        if get_exec().moe.elastic_ep_backend == "mooncake":
            try:
                from mooncake.pg import set_transfer_engine
            except ImportError as e:
                raise ImportError(
                    "Failed to import 'set_transfer_engine' from 'mooncake.pg'. "
                    "Please upgrade your 'mooncake-transfer-engine' "
                    "installation to 0.3.11 or above."
                ) from e
            set_transfer_engine(_mooncake_transfer_engine.engine)

View on GitHub (pinned to 0132848349)

Solutions

1. pip install mooncake-transfer-engine>=0.3.11 --upgrade
2. Verify: python -c 'from mooncake.pg import set_transfer_engine'
3. Or switch elastic EP backend away from mooncake if you cannot upgrade (e.g. use the default backend)

Example fix

# before
python -m sglang.launch_server ... --elastic-ep-backend mooncake
# ImportError: Failed to import 'set_transfer_engine' from 'mooncake.pg' ...

# after
pip install 'mooncake-transfer-engine>=0.3.11' --upgrade
python -m sglang.launch_server ... --elastic-ep-backend mooncake

try:
    from mooncake.pg import set_transfer_engine  # noqa: F401
    ok = True
except ImportError:
    ok = False
if backend == 'mooncake' and not ok:
    raise RuntimeError('mooncake>=0.3.11 required for elastic EP mooncake backend')

try:
    maybe_init_shared_mooncake_transfer_engine()
except ImportError as e:
    if 'mooncake.pg' in str(e):
        # switch elastic EP backend or fail with upgrade instruction
        ...
    raise

When it happens

Trigger: Enabling moe.elastic_ep_backend == 'mooncake' (elastic EP with mooncake transport) on an environment where mooncake-transfer-engine < 0.3.11, so 'from mooncake.pg import set_transfer_engine' fails.

Common situations: Turning on elastic expert parallelism with the mooncake backend on a legacy image; upgrading SGLang to a version that expects mooncake.pg without upgrading mooncake; CI images pinned to an old mooncake wheel.

Related errors

• Please install mooncake by following the instructions at htt
• Mooncake's batch register requires a newer version of moonca
• Mooncake's batch transfer requires mooncake-transfer-engine
• ModelOpt export functionality is not available. Please ensur
• Failed to load serve backend {name!r} from {self._entry_poin

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