unslothai/unsloth · error · ValueError

Whisper dataset needs 'audio' and 'text' columns, got: {data

Error message

Whisper dataset needs 'audio' and 'text' columns, got: {dataset.column_names}

What it means

ValueError raised at the start of Whisper fine-tune preprocessing when column resolution cannot find both an audio and a text column. Whisper training extracts log-mel input_features from 16kHz audio and tokenizes the text as labels, so both columns are required before train/test splitting and feature extraction begin.

Source

Thrown at studio/backend/core/training/trainer.py:2435

        dataset,
        eval_split = None,
        custom_format_mapping = None,
    ):
        """Preprocess dataset for Whisper speech-to-text training.

        Mirrors Whisper.ipynb: extract audio features with Whisper's feature
        extractor, tokenize text labels. Returns (train_data, eval_data),
        each a list of dicts with 'input_features' and 'labels'.
        """
        from datasets import Audio

        WHISPER_SAMPLE_RATE = 16000

        resolved = self._resolve_audio_columns(dataset, custom_format_mapping)
        audio_col = resolved["audio_col"]
        text_col = resolved["text_col"]
        if not audio_col or not text_col:
            raise ValueError(
                f"Whisper dataset needs 'audio' and 'text' columns, got: {dataset.column_names}"
            )

        # Cast audio to 16kHz (Whisper's expected sample rate)
        dataset = dataset.cast_column(audio_col, Audio(sampling_rate = WHISPER_SAMPLE_RATE))

        # Train/eval split (notebook does dataset.train_test_split)
        eval_dataset_raw = None
        if eval_split:
            splits = dataset.train_test_split(test_size = 0.06, seed = 42)
            dataset = splits["train"]
            eval_dataset_raw = splits["test"]

        self._update_progress(status_message = "Processing audio for Whisper...")
        logger.info(
            f"Whisper preprocessing: audio_col='{audio_col}', text_col='{text_col}', "
            f"samples={len(dataset)}\n"
        )

View on GitHub (pinned to 203007d190)

Solutions

Map the transcript column: custom_format_mapping={'sentence': 'text'} (audio usually resolves by Audio type).
Rename columns so 'audio' and 'text' are both present.
Verify the dataset genuinely has aligned audio+transcript pairs for ASR training.

Example fix

// before
dataset  # columns: ['audio', 'sentence']  (Common Voice style)
// after
dataset = dataset.rename_column('sentence', 'text')

Defensive patterns

Strategy: validation

Validate before calling

def whisper_ready(dataset) -> bool:
    return 'audio' in dataset.column_names and 'text' in dataset.column_names

assert whisper_ready(dataset), "Whisper needs 'audio' and 'text' columns"

Type guard

def is_asr_dataset(dataset) -> bool:
    return 'audio' in dataset.column_names and 'text' in dataset.column_names

Try / catch

try:
    train_data, eval_data = trainer._preprocess_whisper_dataset(dataset, mapping, eval_split=True)
except ValueError as e:
    if "Whisper dataset needs" in str(e):
        dataset = dataset.rename_column('sentence', 'text')  # Common Voice style
        train_data, eval_data = trainer._preprocess_whisper_dataset(dataset, mapping, eval_split=True)

Prevention

Rename transcript columns like 'sentence'/'transcript' to 'text' at load time.
Cast the audio column with datasets.Audio(sampling_rate=16000) during preparation.
Run schema validation before starting a Whisper run to avoid wasting setup time.

When it happens

Trigger: Whisper fine-tune with a dataset that has audio but transcripts under an unrecognized column name (or no transcript column at all), or vice versa; custom_format_mapping not supplied for unconventional names.

Common situations: Common ASR datasets using 'sentence' (Common Voice style) or 'transcript' without mapping; CSV imports with generic headers; wrong trainer path chosen for a non-audio task.

Related errors

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