huggingface/transformers · error · ValueError

Invalid return_format: {return_format}. Must be 'base64', 'd

Error message

Invalid return_format: {return_format}. Must be 'base64', 'dict', or 'buffer'

What it means

`HfTrainerDeepSpeedConfig.dtype()` returns the dtype that was recorded by `trainer_config_process(args)` when the Trainer processed its configuration. If `dtype()` is called before that (i.e. the config object exists but the Trainer never ran its DeepSpeed integration hook), `self._dtype` is still None and the accessor raises this ValueError — it is an internal lifecycle assertion, not a user-config problem.

Source

Thrown at src/transformers/audio_utils.py:331

        audio (`str`): Either a local file path or a URL to an audio file
        return_format (`str`): Format to return the audio in:
            - "base64": Base64 encoded string
            - "dict": Dictionary with data and format
            - "buffer": BytesIO object
        timeout (`int`, *optional*): Timeout for URL requests in seconds
        force_mono (`bool`): Whether to convert stereo audio to mono
        sampling_rate (`int`, *optional*): If provided, the audio will be resampled to the specified sampling rate.

    Returns:
        `Union[str, Dict[str, Any], io.BytesIO, None]`:
            - `str`: Base64 encoded audio data (if return_format="base64")
            - `dict`: Dictionary with 'data' (base64 encoded audio data) and 'format' keys (if return_format="dict")
            - `io.BytesIO`: BytesIO object containing audio data (if return_format="buffer")
    """
    requires_backends(load_audio_as, ["librosa"])

    if return_format not in ["base64", "dict", "buffer"]:
        raise ValueError(f"Invalid return_format: {return_format}. Must be 'base64', 'dict', or 'buffer'")

    try:
        # Load audio bytes from URL or file
        audio_bytes = None
        if audio.startswith(("http://", "https://")):
            audio_bytes = _fetch_audio_bytes(audio, timeout=timeout)
        elif os.path.isfile(audio):
            with open(audio, "rb") as audio_file:
                audio_bytes = audio_file.read()
        else:
            raise ValueError(f"File not found: {audio}")

        # Process audio data
        with io.BytesIO(audio_bytes) as audio_file:
            with sf.SoundFile(audio_file) as f:
                audio_array = f.read(dtype="float32")
                original_sr = f.samplerate
                audio_format = f.format

View on GitHub (pinned to a597f97485)

Solutions

1. Only query `dtype()` after TrainingArguments/Trainer creation (which calls `trainer_config_process`)
2. If you must know the dtype early, derive it yourself from `args.torch_dtype`/`transformers.utils.get_parameter_dtype` instead of the config object
3. In custom code, call the integration hook (`deepspeed_config.trainer_config_process(args)`) before reading dtype

Example fix

# before
ds_config = HfTrainerDeepSpeedConfig("ds_config.json")
torch_dtype = ds_config.dtype()  # ValueError: trainer_config_process() wasn't called

# after
args = TrainingArguments(..., deepspeed="ds_config.json")
ds_config.dtype()  # safe: TrainingArguments ran trainer_config_process

ds_config = HfTrainerDeepSpeedConfig("ds_config.json")
assert ds_config._dtype is not None, "call trainer_config_process(args) before reading dtype()"
# or simply: only access .dtype() after TrainingArguments(...) was constructed

When it happens

Trigger: Accessing `HfTrainerDeepSpeedConfig(...).dtype()` immediately after constructing the config object, before `TrainingArguments`/`Trainer` instantiation has called `trainer_config_process`. Typically in scripts that build the DeepSpeed config dict programmatically and probe dtype early, or in custom integrations that grab the global `_hf_deepspeed_config_weak_ref` too soon.

Common situations: Programmatic DeepSpeed config generation; forks of the Trainer that reorder initialization; tests that construct HfTrainerDeepSpeedConfig standalone.

Related errors

• Error loading audio: {e}
• min should be < max (got min: {min}, max: {max})
• function {activation_string} not found in ACT2FN mapping {li
• Incorrect format used for `audio`. Should be a numpy array o
• File not found: {audio}

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