huggingface/transformers · error · ValueError

Please correct the following DeepSpeed config values that mi

Error message

Please correct the following DeepSpeed config values that mismatch TrainingArguments values:\n{mismatches}\nThe easiest method is to set these DeepSpeed config values to 'auto'.

What it means

Error "Please correct the following DeepSpeed config values that mismatch TrainingArguments values:\n{mismatches}\nThe easiest method is to set these DeepSpeed config values to 'auto'." thrown in huggingface/transformers.

Source

Thrown at src/transformers/integrations/deepspeed.py:255

                    "zero_optimization.stage3_param_persistence_threshold",
                    10 * hidden_size,
                )

        # scheduler
        self.fill_match(
            "scheduler.params.total_num_steps",
            num_training_steps,
            "num_training_steps (calculated)",
        )
        self.fill_match(
            "scheduler.params.warmup_num_steps",
            args.get_warmup_steps(num_training_steps),
            "warmup_steps",
        )

        if len(self.mismatches) > 0:
            mismatches = "\n".join(self.mismatches)
            raise ValueError(
                "Please correct the following DeepSpeed config values that mismatch TrainingArguments"
                f" values:\n{mismatches}\nThe easiest method is to set these DeepSpeed config values to 'auto'."
            )


# keep the config object global to be able to access it anywhere during TrainingArguments life-cycle
_hf_deepspeed_config_weak_ref = None


def set_hf_deepspeed_config(hf_deepspeed_config_obj):
    # this is a special weakref global object to allow us to get to Deepspeed config from APIs
    # that don't have an easy way to get to the Deepspeed config outside of the Trainer domain.
    global _hf_deepspeed_config_weak_ref
    # will go away automatically when HfDeepSpeedConfig is destroyed (when TrainingArguments is destroyed)
    _hf_deepspeed_config_weak_ref = weakref.ref(hf_deepspeed_config_obj)


def unset_hf_deepspeed_config():

View on GitHub (pinned to a597f97485)

Solutions

1. Set the mismatched DeepSpeed config values to 'auto' so they inherit from TrainingArguments.
2. Align the DeepSpeed config values with the TrainingArguments values manually.

When it happens

Trigger: Raised in DeepSpeed config validation when DeepSpeed config values conflict with TrainingArguments values.

Common situations: Batch size, learning rate, or precision set differently in ds_config.json and TrainingArguments; both must match or use 'auto'.

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