{"record":{"id":"39c0cccd4b4c72d9","repo":"hiyouga/LlamaFactory","slug":"npuropekernel-requires-torch-npu","errorCode":null,"errorMessage":"NpuRoPEKernel requires torch_npu.","messagePattern":"NpuRoPEKernel requires torch_npu\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/plugins/model_plugins/kernels/ops/rope/npu_rope.py","lineNumber":141,"sourceCode":"    \"qwen3_5\": _default_rope_patch(\"qwen3_5\"),\n    \"qwen3_5_moe\": _default_rope_patch(\"qwen3_5_moe\"),\n}\n\n\n@KernelPlugin(\"npu_fused_rope\").register()\nclass NpuRoPEKernel(BaseKernel):\n    \"\"\"NPU Kernel for Rotary Position Embedding.\"\"\"\n\n    @staticmethod\n    def check_device() -> None:\n        current = get_current_accelerator().type\n        if current != DeviceType.NPU:\n            raise RuntimeError(f\"NpuRoPEKernel requires NPU, current accelerator is {current}.\")\n\n    @staticmethod\n    def check_deps() -> None:\n        if _TORCH_NPU_IMPORT_ERROR is not None:\n            raise RuntimeError(\"NpuRoPEKernel requires torch_npu.\") from _TORCH_NPU_IMPORT_ERROR\n\n    @staticmethod\n    def _apply_model_patches(model_type: str) -> int:\n        patches = _MODEL_TYPE_TO_PATCHES.get(model_type)\n        if patches is None:\n            return 0\n\n        patched_count = 0\n        for module_name, replacements in patches:\n            try:\n                target_module = importlib.import_module(module_name)\n            except Exception as e:\n                logger.warning_rank0_once(f\"Failed to import {module_name} for NPU RoPE kernel: {e}\")\n                continue\n\n            for target_function_name, replacement in replacements:\n                if not hasattr(target_module, target_function_name):\n                    logger.warning_rank0_once(f\"{module_name} has no {target_function_name}, skip NPU RoPE patch.\")","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/model_plugins/kernels/ops/rope/npu_rope.py#L123-L159","documentation":"The npu_fused_rope plugin needs torch_npu to call NPU rotary-position operators. The import error captured at load time is re-raised by check_deps() as RuntimeError chained to the original ImportError.","triggerScenarios":"Applying npu_fused_rope where torch_npu cannot be imported — not installed, incompatible with the installed torch, or CANN runtime environment not loaded.","commonSituations":"Ascend images with broken torch_npu installs; environment activated in a different shell/venv than the trainer; CANN upgrade leaving stale .so files.","solutions":["Install/reinstall torch_npu matching torch+CANN; test `python -c \"import torch_npu\"`","Inspect the chained ImportError for the exact missing symbol or library","Re-source the CANN environment and confirm LD_LIBRARY_PATH includes the toolkit libs"],"exampleFix":"# before\n# RuntimeError: NpuRoPEKernel requires torch_npu.\n# after\npip install torch_npu==<matching> ; python -c \"import torch_npu\"","handlingStrategy":"validation","validationCode":"try:\n    import torch_npu  # noqa: F401\nexcept ImportError:\n    kernels = [k for k in kernels if k != \"npu_fused_rope\"]","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install torch_npu matching torch/CANN; source CANN env","Add import preflight to cluster job wrappers"],"tags":["dependencies","npu","torch-npu","rope"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}