{"record":{"id":"d48a6dff661dc34d","repo":"huggingface/transformers","slug":"finegrained-fp8-kernel-is-missing-required-symbols","errorCode":null,"errorMessage":"finegrained-fp8 kernel is missing required symbols: {', '.join(missing)}. {_MISSING_KERNELS_MESSAGE}","messagePattern":"finegrained-fp8 kernel is missing required symbols: (.+?)\\. (.+?)","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/finegrained_fp8.py","lineNumber":132,"sourceCode":"            \"Failed to load the finegrained-fp8 kernel — check that `kernels-community/finegrained-fp8` \"\n            \"has a build matching the current torch/CUDA.\"\n        )\n\n    matmul = getattr(kernel, \"matmul_2d\", None)\n    batched_matmul = getattr(kernel, \"matmul_batched\", None)\n    grouped_matmul = getattr(kernel, \"matmul_grouped\", None)\n\n    missing = [\n        name\n        for name, attr in [\n            (\"matmul_2d\", matmul),\n            (\"matmul_batched\", batched_matmul),\n            (\"matmul_grouped\", grouped_matmul),\n        ]\n        if attr is None\n    ]\n    if missing:\n        raise ImportError(\n            f\"finegrained-fp8 kernel is missing required symbols: {', '.join(missing)}. {_MISSING_KERNELS_MESSAGE}\"\n        )\n\n    _FINEGRAINED_FP8 = FineGrainedFP8(\n        matmul=matmul,\n        batched_matmul=batched_matmul,\n        grouped_matmul=grouped_matmul,\n    )\n\n\ndef load_finegrained_fp8_kernel() -> FineGrainedFP8:\n    _load_finegrained_fp8_kernel()\n    return _FINEGRAINED_FP8\n\n\ndef _cdiv(a: int, b: int) -> int:\n    \"\"\"Ceiling division.\"\"\"\n    return (a + b - 1) // b","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/finegrained_fp8.py#L114-L150","documentation":"Raised after the finegrained-fp8 kernel module loads but lacks one or more of the required symbols matmul_2d, matmul_batched, or matmul_grouped. Transformers pins an implicit contract on the kernel's API surface; an older (or differently versioned) kernels-community/finegrained-fp8 build that predates one of these entry points fails the getattr(None) check and this ImportError lists exactly which symbols are missing.","triggerScenarios":"load_finegrained_fp8_kernel() when a stale cached build of finegrained-fp8 is present (e.g. cached from an older kernels release) or the published kernel version does not yet export matmul_grouped / matmul_batched.","commonSituations":"A kernels cache directory persisted across a transformers upgrade that started requiring a new symbol; a pinned old commit of the kernel in a lockfile; partially-populated HF cache after an interrupted download.","solutions":["Clear the cached kernel build (HF/kernels cache, e.g. ~/.cache/kernels or the kernels cache dir) so a fresh build is fetched","Upgrade transformers and the kernels package together so the required symbol set matches: pip install -U transformers kernels","Verify what the loaded kernel exports: python -c \"from kernels import lazy_load_kernel; k = lazy_load_kernel('finegrained-fp8'); print([a for a in dir(k) if 'matmul' in a])\""],"exampleFix":"# before\nrm -rf ~/.cache/kernels  # stale build missing matmul_grouped\nload_finegrained_fp8_kernel()  # ImportError: missing required symbols: matmul_grouped\n\n# after: fetch a fresh build matching current transformers\nrm -rf ~/.cache/kernels && pip install -U kernels transformers\nload_finegrained_fp8_kernel()","handlingStrategy":"try-catch","validationCode":"from kernels import lazy_load_kernel\nk = lazy_load_kernel(\"finegrained-fp8\")\nrequired = {\"matmul_2d\", \"matmul_batched\", \"matmul_grouped\"}\nmissing = required - {a for a in required if getattr(k, a, None) is not None}\nassert not missing, f\"stale kernel build, missing {missing}; clear kernels cache\"","typeGuard":null,"tryCatchPattern":"try:\n    load_finegrained_fp8_kernel()\nexcept ImportError as e:\n    if \"missing required symbols\" in str(e):\n        # stale cached build — clear and refetch once, then fail hard if still broken\n        import shutil, pathlib\n        shutil.rmtree(pathlib.Path.home() / \".cache\" / \"kernels\", ignore_errors=True)\n    raise","preventionTips":["Upgrade transformers and kernels in the same change so required symbols match","Clear the kernels cache when downgrading/switching transformers versions","Smoke-test the kernel load at container build time, not at training time"],"tags":["fp8","quantization","kernels","version-mismatch","import-error","cache"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}