vllm-project/vllm · critical · RuntimeError

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

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.

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.

Appendix: 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)