unslothai/unsloth · error · RuntimeError

Decoding is disabled for this feature. Please use Audio(deco

Error message

Decoding is disabled for this feature. Please use Audio(decode=True) instead.

What it means

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.

Source

Thrown at studio/backend/utils/datasets/audio_decode.py:80

        return values[0] if len(values) == 1 else None
    return token_per_repo_id.get(fields["repo_id"])


def _decode_with_soundfile(
    self,
    value: dict,
    token_per_repo_id: Optional[dict] = None,
) -> dict:
    """Stand-in for `datasets.Audio.decode_example` that never needs FFmpeg."""
    import io

    import numpy as np
    import soundfile as sf
    from datasets.download.download_config import DownloadConfig
    from datasets.utils.file_utils import is_local_path, xopen

    if not self.decode:
        raise RuntimeError(
            "Decoding is disabled for this feature. Please use Audio(decode=True) instead."
        )
    path, raw = value["path"], value["bytes"]
    if path is None and raw is None:
        raise ValueError(
            f"An audio sample should have one of 'path' or 'bytes' but both are None in {value}."
        )

    if raw is not None:
        source: Any = io.BytesIO(raw)
    elif is_local_path(path):
        source = path
    else:
        source = xopen(
            path,
            "rb",
            download_config = DownloadConfig(token = _token_for_url(path, token_per_repo_id)),
        )

View on GitHub (pinned to 203007d190)

Solutions

1. Declare the Audio feature with decoding enabled: Audio(decode=True) (or Audio() which decodes by default)
2. If raw access was intentional, read value['bytes'] or value['path'] directly instead of decode_example
3. Re-cast the column: dataset = dataset.cast_column('audio', Audio(decode=True)) before mapping

Example fix

# before
features = Features({'audio': Audio(decode=False)})
sample['audio']  # later decode_example raises

# after
features = Features({'audio': Audio(decode=True)})
# or: dataset = dataset.cast_column('audio', Audio(decode=True))

from datasets import Audio

def assert_audio_decodable(feature) -> None:
    if type(feature).__name__ == "Audio" and not feature.decode:
        raise ValueError("Audio feature has decode=False; decoding will raise RuntimeError")

def is_decoding_audio(feature) -> bool:
    return getattr(feature, "decode", True) is True

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• dataset_streaming requires a plain split name in {field_name
• dataset_streaming streams from the Hub and cannot use the lo
• An audio sample should have one of 'path' or 'bytes' but bot
• scan_dataset requires a single Dataset split, not a DatasetD
• scan_dataset requires a materialized Dataset, not an Iterabl

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/f316c6a052e4c96d. Report an issue: GitHub.