vllm-project/vllm · critical · RuntimeError

MoRIIO is not available. Please ensure the 'mori' package is

Error message

MoRIIO is not available. Please ensure the 'mori' package is installed and properly configured.

What it means

MoRIIOConnectorWorker.__init__ raises RuntimeError when the optional 'mori' package failed to import at module load (is_moriio_available() is False; module import logs 'MoRIIO is not available'). The connector cannot operate without the MoRI-IO transfer library.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/moriio/moriio_connector.py:1082

            if now >= deadline
        ]
        for req_id in stale:
            self._pending_sent_acks.pop(req_id, None)

        connector_output.finished_sending = safe or None


class MoRIIOConnectorWorker:
    """Implementation of Worker side methods"""

    def __init__(
        self,
        vllm_config: VllmConfig,
        engine_id: str,
        kv_cache_config: "KVCacheConfig",
    ):
        if not is_moriio_available():
            raise RuntimeError(
                "MoRIIO is not available. Please ensure the 'mori' package "
                "is installed and properly configured."
            )

        assert vllm_config.kv_transfer_config is not None
        self.moriio_config = MoRIIOConfig.from_vllm_config(vllm_config)
        self.mode = (
            MoRIIOMode.READ if self.moriio_config.read_mode else MoRIIOMode.WRITE
        )

        logger.info("Initializing MoRIIO worker %s", engine_id)

        logging.getLogger("aiter").disabled = True

        # Config.
        self.vllm_config = vllm_config
        assert vllm_config.kv_transfer_config is not None, (
            "kv_transfer_config must be set for MoRIIOConnector"

View on GitHub (pinned to c794754062)

Solutions

Install the mori package into the same uv/.venv environment vLLM runs in and retry
Verify with a direct import in the run environment: the same .venv/bin/python must be able to import mori
Check the earlier 'MoRIIO is not available' log line / import traceback for the underlying cause (missing dep, CUDA mismatch)
Confirm mori is installed on BOTH prefill and decode instances

Example fix

# before: connector enabled but mori missing
uv pip install -e . && vllm serve ... --kv-transfer-config kv_role=kv_producer

# after
uv pip install mori && .venv/bin/python -c "import mori" && vllm serve ... --kv-transfer-config ...

Defensive patterns

Strategy: validation

Validate before calling

from vllm.distributed.kv_transfer.kv_connector.v1.moriio.moriio_connector import is_moriio_available

if not is_moriio_available():
    raise RuntimeError("install the 'mori' package before enabling the moriio KV connector")

# only after the check, build the connector / start vllm with kv_transfer_config

Type guard

def mori_dependency_ready() -> bool:
    try:
        import mori  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    worker = MoRIIOConnectorWorker(vllm_config, engine_id, kv_cache_config)
except RuntimeError as e:
    if "mori" in str(e):
        fail_deployment("mori package missing; install it in this venv")
    raise

Prevention

Add mori to the deployment image/requirements for every P and D instance
Smoke-test `import mori` with the exact runtime interpreter during image build
Treat the 'MoRIIO is not available' log line at startup as a hard failure, not a warning

When it happens

Trigger: Constructing MoRIIOConnectorWorker (i.e. enabling the moriio KV connector via --kv-transfer-config) in an environment where 'import mori' (or its deps) failed.

Common situations: Fresh venv/container without the mori wheel; mori installed for a different Python or CUDA version; GPU/driver requirement of mori unmet so the import partially fails; only one of the P/D instances has it installed.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/371a27cb3165117e. Report an issue: GitHub.