huggingface/transformers · error · ValueError

`problem_type="single_label_classification"` requires `num_l

Error message

`problem_type="single_label_classification"` requires `num_labels > 1`. For binary classification use `num_labels=2`, or use `problem_type="regression"` for a single-output regression head.

What it means

ValueError raised during config post-init when problem_type is 'single_label_classification' but num_labels resolves to 1. Single-label classification mathematically needs at least two classes; a single output is regression, so the config refuses the contradictory combination instead of producing a broken head at runtime.

Source

Thrown at src/transformers/configuration_utils.py:305

            self.dtype = getattr(torch, self.dtype)

        # Keep the default value of `num_labels=2` in case users have saved a classifier with 2 labels
        # Our configs prev wouldn't save `id2label` for 2 labels because it is the default. In all other
        # cases we expect the config dict to have an `id2label` field if it's a clf model, or not otherwise
        if self.id2label is None:
            self.num_labels = kwargs.get("num_labels", self.num_labels if self.num_labels is not None else 2)
        else:
            if kwargs.get("num_labels") is not None and len(self.id2label) != kwargs.get("num_labels"):
                logger.warning(
                    f"You passed `num_labels={kwargs.get('num_labels')}` which is incompatible to "
                    f"the `id2label` map of length `{len(self.id2label)}`."
                )
            # Keys are always strings in JSON so convert ids to int
            self.id2label = {int(key): value for key, value in self.id2label.items()}

        if self.problem_type == "single_label_classification" and self.num_labels == 1:
            raise ValueError(
                '`problem_type="single_label_classification"` requires `num_labels > 1`. For binary '
                'classification use `num_labels=2`, or use `problem_type="regression"` for a '
                "single-output regression head."
            )

        # BC for rotary embeddings. We will pop out legacy keys from kwargs and rename to new format
        if hasattr(self, "rope_parameters"):
            kwargs = self.convert_rope_params_to_dict(**kwargs)
        elif kwargs.get("rope_scaling") and kwargs.get("rope_theta"):
            logger.warning(
                f"{self.__class__.__name__} got `key=rope_scaling` in kwargs but hasn't set it as attribute. "
                "For RoPE standardization you need to set `self.rope_parameters` in model's config. "
            )
            kwargs = self.convert_rope_params_to_dict(**kwargs)

        # Parameters for sequence generation saved in the config are popped instead of loading them.
        for parameter_name in GenerationConfig._get_default_generation_params().keys():
            kwargs.pop(parameter_name, None)

View on GitHub (pinned to a597f97485)

Solutions

1. For binary classification use num_labels=2 (or drop num_labels to let it default)
2. If you truly have one continuous output, set problem_type='regression'
3. If id2label drove num_labels to 1, provide a two-entry id2label for classification

Example fix

# before
cfg = MyConfig(problem_type='single_label_classification', num_labels=1)
# after
cfg = MyConfig(problem_type='single_label_classification', num_labels=2)
# or for one continuous target
cfg = MyConfig(problem_type='regression', num_labels=1)

if problem_type == 'single_label_classification':
    assert num_labels and num_labels > 1, 'use num_labels=2 (binary) or problem_type=regression'

def is_valid_label_setup(problem_type: str, num_labels: int) -> bool:
    return not (problem_type == 'single_label_classification' and num_labels == 1)

try:
    cfg = MyConfig(problem_type=pt, num_labels=n)
except ValueError as e:
    if 'num_labels > 1' in str(e):
        n = 2 if pt == 'single_label_classification' else n
        cfg = MyConfig(problem_type=pt, num_labels=n)
    else:
        raise

When it happens

Trigger: MyConfig(problem_type='single_label_classification', num_labels=1) or num_labels defaulting to 1 via an id2label map of length 1. Also passing id2label={0: 'label'} which sets num_labels=1.

Common situations: Adapting a binary classifier and setting num_labels=1 out of habit from other frameworks; datasets with a single class after filtering; converting a regression checkpoint and forgetting to change problem_type.

Related errors

• out_indices must be a list, got {type(self._out_indices)}
• out_indices must be valid indices for stage_names {self.stag
• out_indices must not contain any duplicates, got {self._out_
• out_indices must be in the same order as stage_names, expect
• out_features and out_indices should have the same length if

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/71550fb6de158460. Report an issue: GitHub.