unslothai/unsloth · error · ValueError

SNAC dataset needs 'audio' and 'text' columns, got: {dataset

Error message

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

What it means

ValueError raised at the start of SNAC preprocessing (audio-language-model path) when _resolve_audio_columns cannot find both audio and text columns. SNAC codecs require the audio (to encode at SNAC_SAMPLE_RATE) and its transcript, so either missing is fatal before any model loading or GPU work happens.

Source

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

        tokenizer = self.tokenizer

        # Orpheus special token IDs (hardcoded in tokenizer vocabulary)
        START_OF_HUMAN = 128259
        END_OF_HUMAN = 128260
        START_OF_AI = 128261
        END_OF_AI = 128262
        START_OF_SPEECH = 128257
        END_OF_SPEECH = 128258
        END_OF_TEXT = 128009
        AUDIO_OFFSET = 128266

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

        # Cast audio so datasets 4.x AudioDecoder objects decode to dicts
        from datasets import Audio

        dataset = dataset.cast_column(audio_col, Audio(sampling_rate = SNAC_SAMPLE_RATE))

        # Sample rate from first example (after cast, always SNAC_SAMPLE_RATE)
        first_audio = dataset[0][audio_col]
        ds_sample_rate = (
            first_audio.get("sampling_rate", SNAC_SAMPLE_RATE)
            if isinstance(first_audio, dict)
            else SNAC_SAMPLE_RATE
        )

        self._update_progress(status_message = "Loading SNAC codec model...")
        logger.info("Loading SNAC codec model...\n")

View on GitHub (pinned to 203007d190)

Solutions

Add custom_format_mapping entries mapping your column names to 'audio' and 'text'.
Rename the columns to conventional audio/text names.
Ensure the dataset genuinely contains both audio and transcripts for SNAC training.

Example fix

// before
dataset  # columns: ['voice', 'transcript_raw']
// after
dataset = dataset.rename_column('voice', 'audio').rename_column('transcript_raw', 'text')

Defensive patterns

Strategy: validation

Validate before calling

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

assert snac_ready(dataset), "SNAC needs 'audio' and 'text' columns"

Type guard

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

Try / catch

try:
    ds = trainer._preprocess_snac_dataset(dataset, mapping)
except ValueError as e:
    if "SNAC dataset needs" in str(e):
        mapping = {**(mapping or {}), 'voice': 'audio', 'transcript': 'text'}
        ds = trainer._preprocess_snac_dataset(dataset, mapping)

Prevention

Use canonical 'audio'/'text' names when preparing SNAC datasets.
Include custom_format_mapping in saved trainer configs for non-standard schemas.
Run a column check as part of the pre-flight before loading SNAC codecs to GPU.

When it happens

Trigger: SNAC fine-tune where the dataset lacks a text column, lacks audio, or has them under names not covered by the resolver/custom_format_mapping; speaker_col is optional (has_source) but audio and text are not.

Common situations: Unmapped column names ('voice', 'transcript_raw'); dataset exported with only audio for codec pretraining; selecting the SNAC model for a plain text LLM dataset.

Related errors

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