{"record":{"id":"41f6ee51fbc98f36","repo":"hiyouga/LlamaFactory","slug":"dim-must-be-specified","errorCode":null,"errorMessage":"dim must be specified.","messagePattern":"dim must be specified\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/accelerator/interface.py","lineNumber":192,"sourceCode":"            )\n        else:\n            self.model_device_mesh = None\n            self.data_device_mesh = None\n\n        self._initialized = True\n        logger.info_rank0(f\"DistributedInterface initialized: {self}.\")\n\n    def __str__(self) -> str:\n        return (\n            f\"DistributedInterface(strategy={self.strategy}), is_distributed={self._is_distributed}, \"\n            f\"current_device={self.current_device}, rank={self._rank}, world_size={self._world_size}, \"\n            f\"model_device_mesh={self.model_device_mesh}, data_device_mesh={self.data_device_mesh}\"\n        )\n\n    def get_device_mesh(self, dim: Dim | None = None) -> DeviceMesh | None:\n        \"\"\"Get device mesh for specified dimension.\"\"\"\n        if dim is None:\n            raise ValueError(\"dim must be specified.\")\n        elif not self._is_distributed:\n            return None\n        elif dim in self.strategy.data_mesh_dim_names:\n            return self.data_device_mesh[dim.value]\n        else:\n            return self.model_device_mesh[dim.value]\n\n    def get_group(self, dim: Dim | None = None) -> Optional[ProcessGroup]:\n        \"\"\"Get process group for specified dimension.\"\"\"\n        if not self._is_distributed or dim is None:\n            return None\n        else:\n            return self.get_device_mesh(dim).get_group()\n\n    def get_rank(self, dim: Dim | None = None) -> int:\n        \"\"\"Get parallel rank for specified dimension.\"\"\"\n        if not self._is_distributed:\n            return 0","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/accelerator/interface.py#L174-L210","documentation":"`DistributedInterface.get_device_mesh(dim)` requires an explicit `Dim` argument; passing `None` (or omitting it) raises this ValueError immediately, before the distributed check. The mesh is a per-dimension lookup (data dims vs model dims), so there is no meaningful default dimension.","triggerScenarios":"Calling `interface.get_device_mesh()` with no arguments, or passing a variable that is `None` (e.g. an optional dim parameter threaded through from a config that was never set).","commonSituations":"Writing a custom plugin/trainer that mirrors a signature with `dim: Dim | None = None` and forwards the default; refactoring code that previously used a hardcoded dimension enum member.","solutions":["Pass an explicit `Dim` member, e.g. `get_device_mesh(Dim.DP)` or `get_device_mesh(Dim.MP)`","Guard optional dims at the call site: only call when the value is not None","Check the `Dim` enum definition in the accelerator interface for the exact member names"],"exampleFix":"# before\nmesh = interface.get_device_mesh()  # ValueError: dim must be specified.\n\n# after\nfrom llamafactory.v1.accelerator.interface import Dim\nmesh = interface.get_device_mesh(Dim.DP)","handlingStrategy":"type-guard","validationCode":"from llamafactory.v1.accelerator.interface import Dim, DistributedInterface\n\ndef mesh_for(interface: DistributedInterface, dim: Dim | None):\n    if dim is None:\n        return None  # caller decides; never call get_device_mesh(None)\n    return interface.get_device_mesh(dim)","typeGuard":"from typing import TypeGuard\nfrom llamafactory.v1.accelerator.interface import Dim\n\ndef is_dim(value: object) -> TypeGuard[Dim]:\n    return isinstance(value, Dim)","tryCatchPattern":null,"preventionTips":["Type optional dims as `Dim | None` and guard before the call","Never copy the `dim: Dim | None = None` default into public wrappers","Keep an enum reference next to mesh code so valid members are visible"],"tags":["v1","api-misuse","distributed-training","device-mesh"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}