{"record":{"id":"f316c6a052e4c96d","repo":"unslothai/unsloth","slug":"decoding-is-disabled-for-this-feature-please-use","errorCode":null,"errorMessage":"Decoding is disabled for this feature. Please use Audio(decode=True) instead.","messagePattern":"Decoding is disabled for this feature\\. Please use Audio\\(decode=True\\) instead\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/datasets/audio_decode.py","lineNumber":80,"sourceCode":"        return values[0] if len(values) == 1 else None\n    return token_per_repo_id.get(fields[\"repo_id\"])\n\n\ndef _decode_with_soundfile(\n    self,\n    value: dict,\n    token_per_repo_id: Optional[dict] = None,\n) -> dict:\n    \"\"\"Stand-in for `datasets.Audio.decode_example` that never needs FFmpeg.\"\"\"\n    import io\n\n    import numpy as np\n    import soundfile as sf\n    from datasets.download.download_config import DownloadConfig\n    from datasets.utils.file_utils import is_local_path, xopen\n\n    if not self.decode:\n        raise RuntimeError(\n            \"Decoding is disabled for this feature. Please use Audio(decode=True) instead.\"\n        )\n    path, raw = value[\"path\"], value[\"bytes\"]\n    if path is None and raw is None:\n        raise ValueError(\n            f\"An audio sample should have one of 'path' or 'bytes' but both are None in {value}.\"\n        )\n\n    if raw is not None:\n        source: Any = io.BytesIO(raw)\n    elif is_local_path(path):\n        source = path\n    else:\n        source = xopen(\n            path,\n            \"rb\",\n            download_config = DownloadConfig(token = _token_for_url(path, token_per_repo_id)),\n        )","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/datasets/audio_decode.py#L62-L98","documentation":"RuntimeError from an FFmpeg-free stand-in for datasets.Audio.decode_example installed by the studio backend. It faithfully reproduces upstream HF datasets behavior: when the Audio feature was constructed with decode=False, calling decode_example refuses instead of returning raw bytes, pointing the caller to Audio(decode=True). The patched path exists so audio decoding works without FFmpeg via soundfile, but it does not change the decode flag contract.","triggerScenarios":"Defining a dataset schema with Audio(decode=False) and then letting any code path call feature.decode_example(value) — e.g. dataset.map on an audio column, or collators that expect decoded arrays while the feature was declared undecoded.","commonSituations":"Loading audio datasets with decoding disabled to save memory/I/O, then passing them to a preprocessing function that implicitly decodes; mixing raw-bytes workflows with training code that expects {'array', 'sampling_rate'} dicts.","solutions":["Declare the Audio feature with decoding enabled: Audio(decode=True) (or Audio() which decodes by default)","If raw access was intentional, read value['bytes'] or value['path'] directly instead of decode_example","Re-cast the column: dataset = dataset.cast_column('audio', Audio(decode=True)) before mapping"],"exampleFix":"# before\nfeatures = Features({'audio': Audio(decode=False)})\nsample['audio']  # later decode_example raises\n\n# after\nfeatures = Features({'audio': Audio(decode=True)})\n# or: dataset = dataset.cast_column('audio', Audio(decode=True))","handlingStrategy":"validation","validationCode":"from datasets import Audio\n\ndef assert_audio_decodable(feature) -> None:\n    if type(feature).__name__ == \"Audio\" and not feature.decode:\n        raise ValueError(\"Audio feature has decode=False; decoding will raise RuntimeError\")","typeGuard":"def is_decoding_audio(feature) -> bool:\n    return getattr(feature, \"decode\", True) is True","tryCatchPattern":null,"preventionTips":["Declare Audio() (decode defaults to True) unless you specifically want raw bytes","Audit dataset features with dataset.features before map/collate steps that expect decoded arrays","Use cast_column('audio', Audio(decode=True)) at the boundary between raw-storage and training pipelines"],"tags":["audio","datasets","huggingface","decoding"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}