{"record":{"id":"3fa63a4d6edcacea","repo":"huggingface/transformers","slug":"workspace-must-be-set-before-calling-forward","errorCode":null,"errorMessage":"Workspace must be set before calling forward","messagePattern":"Workspace must be set before calling forward","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/higgs.py","lineNumber":536,"sourceCode":"        )\n        self.tables = nn.Parameter(torch.empty((2**num_bits,), dtype=dtype, device=device), requires_grad=False)\n        self.tables2 = nn.Parameter(\n            torch.empty((2**num_bits, 2**num_bits, 2), dtype=dtype, device=device), requires_grad=False\n        )\n\n        if bias:\n            self.bias = nn.Parameter(torch.empty(out_features, device=device, dtype=dtype), requires_grad=False)\n        else:\n            self.register_parameter(\"bias\", None)\n\n        self.workspace = None  # must be set externally to be reused among layers\n        self.tune_metadata: TuneMetaData = None  # must be set externally because architecture dependent\n\n    def forward(self, x):\n        x = pad_to_block(x, [-1], self.hadamard_size)\n\n        if self.workspace is None:\n            raise Exception(\"Workspace must be set before calling forward\")\n\n        return qgemm_v2(\n            x,\n            self.weight,\n            self.scales,\n            self.tables,\n            self.tables2.view(dtype=torch.float32),\n            self.workspace,\n            self.tune_metadata,\n            hadamard_size=self.hadamard_size,\n        )\n\n\ndef replace_with_higgs_linear(model, modules_to_not_convert: list[str] | None = None, quantization_config=None):\n    \"\"\"\n    Public method that replaces the Linear layers of the given model with HIGGS quantized layers.\n\n    Args:","sourceCodeStart":518,"sourceCodeEnd":554,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/higgs.py#L518-L554","documentation":"`HiggsLinear` (Higgs quantized linear layer) relies on an external vLLM-style kernel (`qgemm_v2`) that needs a preallocated `workspace` buffer and `tune_metadata`, both intentionally left as None at construction because they are architecture/GPU dependent and meant to be shared across layers. Calling `forward()` before those attributes are populated raises this Exception.","triggerScenarios":"Instantiating `HiggsLinear` and immediately running `layer(x)` without first assigning `layer.workspace = torch.empty(...)` and `layer.tune_metadata = ...` (typically obtained via the kernel's tuning routine per GPU architecture), e.g. in a plain PyTorch training loop that never calls the vLLM/flashinfer tune step.","commonSituations":"Using Higgs quantization outside the intended vLLM-style inference stack where tuning is done up front; moving code to a new GPU and forgetting to re-run tuning; unit-testing the layer in isolation.","solutions":["Run the kernel tuning step for your GPU and assign the results before the first forward: set `layer.workspace` and `layer.tune_metadata` (see vLLM's `tune`/`qgemm` workspace APIs the integration is modeled on).","Share one workspace across all HiggsLinear layers (it is deliberately external for reuse) but tune once per architecture.","For quick tests, verify wiring with `layer.weight`/dequantized matmul instead of calling `forward()` untuned."],"exampleFix":"# before\nlin = HiggsLinear(in_features, out_features, true_seqlen=True)\ny = lin(x)  # Exception: Workspace must be set before calling forward\n\n# after (vLLM-style tuning)\nfrom vllm import _custom_ops as ops\nlin.workspace, lin.tune_metadata = ops.tune(\n    lin.weight, lin.tables, lin.tables2, lin.scales, 1.0, 10, lin.hadamard_size\n)\ny = lin(x)","handlingStrategy":"validation","validationCode":"assert lin.workspace is not None and lin.tune_metadata is not None, (\n    \"run kernel tuning and assign workspace/tune_metadata before forward\"\n)","typeGuard":"def higgs_linear_ready(lin) -> bool:\n    return lin.workspace is not None and lin.tune_metadata is not None","tryCatchPattern":"try:\n    y = lin(x)\nexcept Exception as e:\n    if \"Workspace must be set\" not in str(e):\n        raise\n    tune_and_assign(lin)  # run kernel tuning, set workspace/tune_metadata\n    y = lin(x)","preventionTips":["Centralize workspace/tune setup right after model construction, before any forward pass.","Reuse one tuned workspace across layers; tune once per GPU architecture.","Add a preflight assert in test harnesses that exercise HiggsLinear."],"tags":["quantization","higgs","vllm-kernel","missing-setup","runtime-state"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}