{"record":{"id":"32eeca2fac99d354","repo":"huggingface/transformers","slug":"invalid-return-format-return-format-must-be-b","errorCode":null,"errorMessage":"Invalid return_format: {return_format}. Must be 'base64', 'dict', or 'buffer'","messagePattern":"Invalid return_format: (.+?)\\. Must be 'base64', 'dict', or 'buffer'","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":331,"sourceCode":"        audio (`str`): Either a local file path or a URL to an audio file\n        return_format (`str`): Format to return the audio in:\n            - \"base64\": Base64 encoded string\n            - \"dict\": Dictionary with data and format\n            - \"buffer\": BytesIO object\n        timeout (`int`, *optional*): Timeout for URL requests in seconds\n        force_mono (`bool`): Whether to convert stereo audio to mono\n        sampling_rate (`int`, *optional*): If provided, the audio will be resampled to the specified sampling rate.\n\n    Returns:\n        `Union[str, Dict[str, Any], io.BytesIO, None]`:\n            - `str`: Base64 encoded audio data (if return_format=\"base64\")\n            - `dict`: Dictionary with 'data' (base64 encoded audio data) and 'format' keys (if return_format=\"dict\")\n            - `io.BytesIO`: BytesIO object containing audio data (if return_format=\"buffer\")\n    \"\"\"\n    requires_backends(load_audio_as, [\"librosa\"])\n\n    if return_format not in [\"base64\", \"dict\", \"buffer\"]:\n        raise ValueError(f\"Invalid return_format: {return_format}. Must be 'base64', 'dict', or 'buffer'\")\n\n    try:\n        # Load audio bytes from URL or file\n        audio_bytes = None\n        if audio.startswith((\"http://\", \"https://\")):\n            audio_bytes = _fetch_audio_bytes(audio, timeout=timeout)\n        elif os.path.isfile(audio):\n            with open(audio, \"rb\") as audio_file:\n                audio_bytes = audio_file.read()\n        else:\n            raise ValueError(f\"File not found: {audio}\")\n\n        # Process audio data\n        with io.BytesIO(audio_bytes) as audio_file:\n            with sf.SoundFile(audio_file) as f:\n                audio_array = f.read(dtype=\"float32\")\n                original_sr = f.samplerate\n                audio_format = f.format","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L313-L349","documentation":"`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.","triggerScenarios":"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.","commonSituations":"Programmatic DeepSpeed config generation; forks of the Trainer that reorder initialization; tests that construct HfTrainerDeepSpeedConfig standalone.","solutions":["Only query `dtype()` after TrainingArguments/Trainer creation (which calls `trainer_config_process`)","If you must know the dtype early, derive it yourself from `args.torch_dtype`/`transformers.utils.get_parameter_dtype` instead of the config object","In custom code, call the integration hook (`deepspeed_config.trainer_config_process(args)`) before reading dtype"],"exampleFix":"# before\nds_config = HfTrainerDeepSpeedConfig(\"ds_config.json\")\ntorch_dtype = ds_config.dtype()  # ValueError: trainer_config_process() wasn't called\n\n# after\nargs = TrainingArguments(..., deepspeed=\"ds_config.json\")\nds_config.dtype()  # safe: TrainingArguments ran trainer_config_process","handlingStrategy":"validation","validationCode":"ds_config = HfTrainerDeepSpeedConfig(\"ds_config.json\")\nassert ds_config._dtype is not None, \"call trainer_config_process(args) before reading dtype()\"\n# or simply: only access .dtype() after TrainingArguments(...) was constructed","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat HfTrainerDeepSpeedConfig.dtype() as valid only after Trainer/TrainingArguments setup","Derive dtype independently (args.torch_dtype) in code that runs earlier"],"tags":["deepspeed","trainer","lifecycle","dtype"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}