{"record":{"id":"589367e2c496c8b7","repo":"vllm-project/vllm","slug":"torch-shm-is-known-to-fail-without-vllm-worker-mul","errorCode":null,"errorMessage":"torch_shm is known to fail without VLLM_WORKER_MULTIPROC_METHOD set to spawn","messagePattern":"torch_shm is known to fail without VLLM_WORKER_MULTIPROC_METHOD set to spawn","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1266,"sourceCode":"        if (\n            self.speculative_config is not None\n            and self.scheduler_config.async_scheduling\n            and self.model_config is not None\n            and not self.model_config.disable_cascade_attn\n        ):\n            logger.warning_once(\n                \"Disabling cascade attention (not yet compatible with \"\n                \"async speculative decoding).\",\n            )\n            self.model_config.disable_cascade_attn = True\n\n        if (\n            self.model_config is not None\n            and self.model_config.multimodal_config is not None\n            and self.model_config.multimodal_config.mm_tensor_ipc == \"torch_shm\"\n            and os.environ.get(\"VLLM_WORKER_MULTIPROC_METHOD\") != \"spawn\"\n        ):\n            raise ValueError(\n                \"torch_shm is known to fail without \"\n                \"VLLM_WORKER_MULTIPROC_METHOD set to spawn\"\n            )\n\n        if (\n            self.model_config is not None\n            and self.scheduler_config.enable_chunked_prefill\n            and self.model_config.dtype == torch.float32\n            and current_platform.get_device_capability() == (7, 5)\n        ):\n            logger.warning_once(\n                \"Turing devices tensor cores do not support float32 matmul. \"\n                \"To workaround this limitation, vLLM will set 'ieee' input \"\n                \"precision for chunked prefill triton kernels.\"\n            )\n\n        if self.model_config is not None and self.model_config.enforce_eager:\n            logger.warning_once(","sourceCodeStart":1248,"sourceCodeEnd":1284,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1248-L1284","documentation":"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'.","triggerScenarios":"Setting `--mm-tensor-ipc torch_shm` (or the multimodal config equivalent) without exporting `VLLM_WORKER_MULTIPROC_METHOD=spawn` in the environment.","commonSituations":"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.","solutions":["Export `VLLM_WORKER_MULTIPROC_METHOD=spawn` before launching vLLM.","Or use the default mm_tensor_ipc transport (remove the torch_shm override)."],"exampleFix":"# before\nvllm serve Qwen/Qwen2.5-VL-7B-Instruct --mm-tensor-ipc torch_shm\n\n# after\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nvllm serve Qwen/Qwen2.5-VL-7B-Instruct --mm-tensor-ipc torch_shm","handlingStrategy":"validation","validationCode":"import os\nif mm_tensor_ipc == \"torch_shm\" and os.environ.get(\"VLLM_WORKER_MULTIPROC_METHOD\") != \"spawn\":\n    os.environ[\"VLLM_WORKER_MULTIPROC_METHOD\"] = \"spawn\"  # set BEFORE engine start","typeGuard":null,"tryCatchPattern":"try:\n    LLM(mm_tensor_ipc=\"torch_shm\", ...)\nexcept ValueError as e:\n    if \"torch_shm\" in str(e):\n        os.environ[\"VLLM_WORKER_MULTIPROC_METHOD\"] = \"spawn\"\n        LLM(mm_tensor_ipc=\"torch_shm\", ...)\n    else:\n        raise","preventionTips":["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"],"tags":["multimodal","shared-memory","environment","multiprocessing"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}