{"record":{"id":"fdfcd0a665623992","repo":"huggingface/transformers","slug":"attention-mask-passed-to-generate-must-be-2d","errorCode":null,"errorMessage":"`attention_mask` passed to `generate` must be 2D.","messagePattern":"`attention_mask` passed to `generate` must be 2D\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/utils.py","lineNumber":2562,"sourceCode":"                    logger.warning(\n                        \"A decoder-only architecture is being used, but right-padding was detected! For correct \"\n                        \"generation results, please set `padding_side='left'` when initializing the tokenizer.\"\n                    )\n\n        # 4. Define other model kwargs\n        # decoder-only models with inputs_embeds forwarding must use caching (otherwise we can't detect whether we are\n        # generating the first new token or not, and we only want to use the embeddings for the first new token)\n        if not self.config.is_encoder_decoder and model_input_name == \"inputs_embeds\":\n            generation_config.use_cache = True\n\n        if not kwargs_has_attention_mask and not self.config.is_encoder_decoder and accepts_attention_mask:\n            model_kwargs[\"attention_mask\"] = self._prepare_attention_mask_for_generation(\n                inputs_tensor, generation_config, model_kwargs\n            )\n        elif kwargs_has_attention_mask:\n            # TODO (joao): generalize this check with other types of inputs\n            if model_input_name == \"input_ids\" and len(model_kwargs[\"attention_mask\"].shape) > 2:\n                raise ValueError(\"`attention_mask` passed to `generate` must be 2D.\")\n\n        kwargs_has_position_ids = model_kwargs.get(\"position_ids\", None) is not None\n        accepts_position_ids = \"position_ids\" in set(inspect.signature(self.forward).parameters.keys())\n        if not kwargs_has_position_ids and accepts_position_ids and not self.config.is_encoder_decoder:\n            model_kwargs[\"position_ids\"] = self._prepare_position_ids_for_generation(inputs_tensor, model_kwargs)\n\n        if self.config.is_encoder_decoder and \"encoder_outputs\" not in model_kwargs:\n            # if model is encoder decoder encoder_outputs are created and added to `model_kwargs`\n            model_kwargs = self._prepare_encoder_decoder_kwargs_for_generation(\n                inputs_tensor, model_kwargs, model_input_name, generation_config\n            )\n\n        # 5. Prepare `input_ids` which will be used for auto-regressive generation\n        if self.config.is_encoder_decoder:\n            input_ids, model_kwargs = self._prepare_decoder_input_ids_for_generation(\n                batch_size=batch_size,\n                model_input_name=model_input_name,\n                model_kwargs=model_kwargs,","sourceCodeStart":2544,"sourceCodeEnd":2580,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/utils.py#L2544-L2580","documentation":"Error \"`attention_mask` passed to `generate` must be 2D.\" thrown in huggingface/transformers.","triggerScenarios":"Raised in generate() input preparation when the attention_mask tensor has a rank other than 2.","commonSituations":"Passing a 1D or 3D attention_mask to generate(), often from manual tensor construction instead of tokenizer output.","solutions":["Pass a 2D `attention_mask` of shape (batch_size, sequence_length).","Expand a 1D mask with `mask.unsqueeze(0)` for batch size 1."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}