{"record":{"id":"5d61ebcebdc06982","repo":"Lightning-AI/pytorch-lightning","slug":"str-transformer-engine-available","errorCode":null,"errorMessage":"str(_TRANSFORMER_ENGINE_AVAILABLE)","messagePattern":"str\\(_TRANSFORMER_ENGINE_AVAILABLE\\)","errorType":"exception","errorClass":"ModuleNotFoundError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/plugins/precision/transformer_engine.py","lineNumber":76,"sourceCode":"\n        Support for FP8 in the linear layers with this plugin is currently limited to tensors\n        with shapes where the dimensions are divisible by 8 and 16 respectively. You might want to add padding to your\n        inputs to conform to this restriction.\n\n    \"\"\"\n\n    precision: Literal[\"transformer-engine\", \"transformer-engine-float16\"] = \"transformer-engine\"\n\n    def __init__(\n        self,\n        *,\n        weights_dtype: torch.dtype,\n        recipe: Optional[Union[Mapping[str, Any], \"DelayedScaling\"]] = None,\n        replace_layers: Optional[bool] = None,\n        fallback_compute_dtype: Optional[torch.dtype] = None,\n    ) -> None:\n        if not _TRANSFORMER_ENGINE_AVAILABLE:\n            raise ModuleNotFoundError(str(_TRANSFORMER_ENGINE_AVAILABLE))\n        from transformer_engine.common.recipe import DelayedScaling\n\n        if recipe is None:\n            recipe = DelayedScaling()\n        elif isinstance(recipe, Mapping):\n            recipe = dict(recipe)  # copy\n            if \"fp8_format\" in recipe:\n                from transformer_engine.common.recipe import Format\n\n                recipe[\"fp8_format\"] = getattr(Format, recipe[\"fp8_format\"])\n            recipe = DelayedScaling(**recipe)\n\n        self.weights_dtype = weights_dtype\n        self.recipe = recipe\n        self.replace_layers = replace_layers\n        self.fallback_compute_dtype = fallback_compute_dtype or weights_dtype\n\n    @override","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/plugins/precision/transformer_engine.py#L58-L94","documentation":"TransformerEnginePrecision requires the NVIDIA Transformer Engine package. The module-level import check failed and stored the exception message in _TRANSFORMER_ENGINE_AVAILABLE; __init__ re-raises it as ModuleNotFoundError when the plugin is instantiated on a machine without the package (or without a compatible GPU/build).","triggerScenarios":"Instantiating TransformerEnginePrecision(...) when 'import transformer_engine' fails — package not installed, CPU-only machine, or CUDA version unsupported by the wheels you installed.","commonSituations":"Running a training script written for H100/FP8 on a dev box or CI runner without transformer_engine installed; installing a transformer_engine build mismatched with the installed torch/CUDA version so the import fails.","solutions":["pip install transformer_engine (preferably a build matching your torch and CUDA version, e.g. the +cu12xyz variant)","Verify with 'python -c \"import transformer_engine\"' that the import actually succeeds in the target environment","If FP8 is not needed, switch to a different precision plugin such as MixedPrecision('bf16-mixed')"],"exampleFix":"# before\nprecision = TransformerEnginePrecision(weights_dtype=torch.float8_e4m3fn, ...)\n# after (shell)\npip install transformer_engine\n# or in code, fall back:\ntry:\n    precision = TransformerEnginePrecision(...)\nexcept ModuleNotFoundError:\n    precision = MixedPrecision(\"bf16-mixed\")","handlingStrategy":"fallback","validationCode":"try:\n    import transformer_engine  # noqa\n    available = True\nexcept ImportError:\n    available = False\nif not available:\n    # choose another precision plugin instead of constructing TransformerEnginePrecision","typeGuard":"import importlib.util\n\ndef transformer_engine_available() -> bool:\n    return importlib.util.find_spec(\"transformer_engine\") is not None","tryCatchPattern":"try:\n    precision = TransformerEnginePrecision(weights_dtype=torch.float8_e4m3fn)\nexcept ModuleNotFoundError:\n    precision = MixedPrecision(\"bf16-mixed\")","preventionTips":["Pin a transformer_engine build matching your torch/CUDA","Gate FP8 code paths behind an availability check"],"tags":["transformer-engine","fp8","missing-dependency","gpu","pytorch-lightning"],"backgroundTag":"missing-optional-dependency","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}