huggingface/transformers · error · ValueError

SquadProcessor should be instantiated via SquadV1Processor o

Error message

SquadProcessor should be instantiated via SquadV1Processor or SquadV2Processor

What it means

Raised by SquadProcessor.get_train_examples when the instance's train_file attribute is None. SquadProcessor is an abstract base: only SquadV1Processor (train-v1.1.json) and SquadV2Processor (train-v2.0.json) set train_file, so instantiating the base class directly and asking for training data is a misuse the class detects explicitly.

Source

Thrown at src/transformers/data/processors/squad.py:513

            examples.append(self._get_example_from_tensor_dict(tensor_dict, evaluate=evaluate))

        return examples

    def get_train_examples(self, data_dir, filename=None):
        """
        Returns the training examples from the data directory.

        Args:
            data_dir: Directory containing the data files used for training and evaluating.
            filename: None by default, specify this if the training file has a different name than the original one
                which is `train-v1.1.json` and `train-v2.0.json` for squad versions 1.1 and 2.0 respectively.

        """
        if data_dir is None:
            data_dir = ""

        if self.train_file is None:
            raise ValueError("SquadProcessor should be instantiated via SquadV1Processor or SquadV2Processor")

        with open(
            os.path.join(data_dir, self.train_file if filename is None else filename), "r", encoding="utf-8"
        ) as reader:
            input_data = json.load(reader)["data"]
        return self._create_examples(input_data, "train")

    def get_dev_examples(self, data_dir, filename=None):
        """
        Returns the evaluation example from the data directory.

        Args:
            data_dir: Directory containing the data files used for training and evaluating.
            filename: None by default, specify this if the evaluation file has a different name than the original one
                which is `dev-v1.1.json` and `dev-v2.0.json` for squad versions 1.1 and 2.0 respectively.
        """
        if data_dir is None:
            data_dir = ""

View on GitHub (pinned to a597f97485)

Solutions

1. Instantiate a concrete subclass: SquadV1Processor() or SquadV2Processor() depending on your data version.
2. In custom subclasses, set self.train_file and self.dev_file in __init__ before calling get_train_examples.
3. If the file has a nonstandard name, you can also pass filename=... to get_train_examples on a concrete subclass.

Example fix

# before
processor = SquadProcessor()
examples = processor.get_train_examples('squad_data/')  # raises

# after
processor = SquadV2Processor()
examples = processor.get_train_examples('squad_data/')

from transformers.data.processors.squad import SquadV1Processor, SquadV2Processor

processor = SquadV2Processor() if args.version_2_with_negative else SquadV1Processor()
assert processor.train_file is not None  # concrete subclasses always set it

from transformers.data.processors.squad import SquadProcessor

def is_concrete_squad_processor(p: SquadProcessor) -> bool:
    return getattr(p, 'train_file', None) is not None

When it happens

Trigger: processor = SquadProcessor(); processor.get_train_examples('data/squad'). Also reachable by subclassing SquadProcessor without assigning train_file/dev_file.

Common situations: Generic processor-selection code that instantiates the base class as a default; custom SQuAD-format processors that forget to set train_file; refactors that changed which class gets constructed.

Related errors

• No valid predictions
• PyTorch must be installed to return a PyTorch dataset.
• db_range must be greater than zero
• Stage_names must be set for transformers backbones
• out_features must be a list got {type(self._out_features)}

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