dataset_mixture must be a dictionary with a 'datasets' key.

Error message

dataset_mixture must be a dictionary with a 'datasets' key. Expected format: {'datasets': [...], 'seed': int}

What it means

When dataset_mixture is supplied it must be a dict containing a 'datasets' key (the expected format is {'datasets': [...], 'seed': int}). __post_init__ validates this and raises if the value is not a dict or lacks 'datasets', since the mixture-building code cannot proceed without the list of dataset specs.

Source

Thrown at src/open_r1/configs.py:84

                test_split_size: 0.1
    """

    # Override the dataset_name to make it optional
    dataset_name: Optional[str] = field(
        default=None, metadata={"help": "Dataset name. Can be omitted if using dataset_mixture."}
    )
    dataset_mixture: Optional[dict[str, Any]] = field(
        default=None,
        metadata={"help": "Configuration for creating dataset mixtures with advanced options like shuffling."},
    )

    def __post_init__(self):
        if self.dataset_name is None and self.dataset_mixture is None:
            raise ValueError("Either `dataset_name` or `dataset_mixture` must be provided")

        if self.dataset_mixture is not None:
            if not isinstance(self.dataset_mixture, dict) or "datasets" not in self.dataset_mixture:
                raise ValueError(
                    "dataset_mixture must be a dictionary with a 'datasets' key. "
                    "Expected format: {'datasets': [...], 'seed': int}"
                )

            datasets_list = []
            datasets_data = self.dataset_mixture.get("datasets", [])

            if isinstance(datasets_data, list):
                for dataset_config in datasets_data:
                    datasets_list.append(
                        DatasetConfig(
                            id=dataset_config.get("id"),
                            config=dataset_config.get("config"),
                            split=dataset_config.get("split", "train"),
                            columns=dataset_config.get("columns"),
                            weight=dataset_config.get("weight", 1.0),
                        )
                    )

View on GitHub (pinned to 1416fa0cf2)

Solutions

Wrap the dataset list under a 'datasets' key: {"datasets": [{"id": "org/name", "config": "default", "split": "train"}], "seed": 42}.
Ensure dataset_mixture is a plain dict, not a list or string.
Fix typos in the 'datasets' key name.

Example fix

// before
dataset_mixture=["HuggingFaceH4/ultrachat_200k"]  # not a dict -> ValueError
// after
dataset_mixture={"datasets": [{"id": "HuggingFaceH4/ultrachat_200k"}], "seed": 42}

Defensive patterns

Strategy: type-guard

Validate before calling

if mixture is not None and (not isinstance(mixture, dict) or "datasets" not in mixture):
    raise ValueError("dataset_mixture must be a dict with a 'datasets' key")

Type guard

def is_valid_mixture(m) -> bool:
    return isinstance(m, dict) and isinstance(m.get("datasets"), list)

Try / catch

try:
    cfg = DatasetConfig(dataset_mixture=mixture)
except ValueError as e:
    if "'datasets' key" in str(e):
        mixture = {"datasets": mixture if isinstance(mixture, list) else [mixture], "seed": 0}
        cfg = DatasetConfig(dataset_mixture=mixture)
    else:
        raise

Prevention

Follow the documented shape: {'datasets': [...], 'seed': int}
Never pass a bare list/string as dataset_mixture
Unit-test config loading from YAML before submitting jobs

When it happens

Trigger: Passing dataset_mixture as a non-dict (e.g. a list of datasets directly, a string, or None-like value), or a dict that omits the 'datasets' key, e.g. dataset_mixture={"seed": 0}.

Common situations: Migrating from dataset_name to dataset_mixture and passing just a list of dataset IDs; YAML parsing turning the mixture into something unexpected; typo like 'dataset' instead of 'datasets'.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of huggingface/open-r1@1416fa0cf2 (2026-08-30). Data as JSON: /api/errors/e70d6fcab2ef2ee5. Report an issue: GitHub.