vllm-project/vllm · error · ValueError

torch_shm is known to fail without VLLM_WORKER_MULTIPROC_MET

Error message

torch_shm is known to fail without VLLM_WORKER_MULTIPROC_METHOD set to spawn

What it means

The `torch_shm` multimodal tensor IPC path (mm_tensor_ipc) passes tensors between processes via shared memory and is known to break unless worker processes are started with the 'spawn' method. VllmConfig checks `VLLM_WORKER_MULTIPROC_METHOD` and refuses to start when mm_tensor_ipc='torch_shm' and the env var is not 'spawn'.

Source

Thrown at vllm/config/vllm.py:1266

        if (
            self.speculative_config is not None
            and self.scheduler_config.async_scheduling
            and self.model_config is not None
            and not self.model_config.disable_cascade_attn
        ):
            logger.warning_once(
                "Disabling cascade attention (not yet compatible with "
                "async speculative decoding).",
            )
            self.model_config.disable_cascade_attn = True

        if (
            self.model_config is not None
            and self.model_config.multimodal_config is not None
            and self.model_config.multimodal_config.mm_tensor_ipc == "torch_shm"
            and os.environ.get("VLLM_WORKER_MULTIPROC_METHOD") != "spawn"
        ):
            raise ValueError(
                "torch_shm is known to fail without "
                "VLLM_WORKER_MULTIPROC_METHOD set to spawn"
            )

        if (
            self.model_config is not None
            and self.scheduler_config.enable_chunked_prefill
            and self.model_config.dtype == torch.float32
            and current_platform.get_device_capability() == (7, 5)
        ):
            logger.warning_once(
                "Turing devices tensor cores do not support float32 matmul. "
                "To workaround this limitation, vLLM will set 'ieee' input "
                "precision for chunked prefill triton kernels."
            )

        if self.model_config is not None and self.model_config.enforce_eager:
            logger.warning_once(

View on GitHub (pinned to c794754062)

Solutions

Export `VLLM_WORKER_MULTIPROC_METHOD=spawn` before launching vLLM.
Or use the default mm_tensor_ipc transport (remove the torch_shm override).

Example fix

# before
vllm serve Qwen/Qwen2.5-VL-7B-Instruct --mm-tensor-ipc torch_shm

# after
export VLLM_WORKER_MULTIPROC_METHOD=spawn
vllm serve Qwen/Qwen2.5-VL-7B-Instruct --mm-tensor-ipc torch_shm

Defensive patterns

Strategy: validation

Validate before calling

import os
if mm_tensor_ipc == "torch_shm" and os.environ.get("VLLM_WORKER_MULTIPROC_METHOD") != "spawn":
    os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"  # set BEFORE engine start

Try / catch

try:
    LLM(mm_tensor_ipc="torch_shm", ...)
except ValueError as e:
    if "torch_shm" in str(e):
        os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"
        LLM(mm_tensor_ipc="torch_shm", ...)
    else:
        raise

Prevention

Set VLLM_WORKER_MULTIPROC_METHOD=spawn in the container/service spec, not just the shell
Env-var checks belong in launch wrappers for multimodal workloads

When it happens

Trigger: Setting `--mm-tensor-ipc torch_shm` (or the multimodal config equivalent) without exporting `VLLM_WORKER_MULTIPROC_METHOD=spawn` in the environment.

Common situations: Optimizing multimodal input transfer (images/video) on multi-GPI workers using torch shared memory, but launching from a wrapper (docker, systemd, k8s) that does not propagate the env var.

Related errors

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