unslothai/unsloth · error · ValueError

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

Error message

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

What it means

ValueError raised at the start of BiCodec (Spark-TTS) preprocessing when column resolution finds no audio or no text column. Speaker column is optional, but audio and text are mandatory: audio is cast with Audio() for datasets 4.x decoding, then encoded with the BiCodecTokenizer. Missing either column aborts before the tokenizer is loaded.

Source

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

        self._update_progress(status_message = "Preparing Spark-TTS codec source...")
        spark_code_dir = ensure_spark_tts_source(self._spark_tts_repo_dir)
        self._spark_tts_code_dir = spark_code_dir
        BiCodecTokenizer = import_sparktts_module(
            "sparktts.models.audio_tokenizer",
            spark_code_dir,
        ).BiCodecTokenizer
        audio_volume_normalize = import_sparktts_module(
            "sparktts.utils.audio",
            spark_code_dir,
        ).audio_volume_normalize

        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"BiCodec dataset needs 'audio' and 'text' columns, got: {dataset.column_names}"
            )

        # Cast so datasets 4.x AudioDecoder objects decode to dicts. No resample here --
        # BiCodec's target_sr may differ; the loop does it.
        from datasets import Audio

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

        self._update_progress(status_message = "Loading BiCodec tokenizer...")
        logger.info("Loading BiCodec tokenizer...\n")
        audio_tokenizer = BiCodecTokenizer(self._spark_tts_repo_dir, device)

        target_sr = audio_tokenizer.config["sample_rate"]

        self._update_progress(status_message = "Encoding audio with BiCodec...")
        logger.info(
            f"BiCodec preprocessing: audio_col='{audio_col}', text_col='{text_col}', "

View on GitHub (pinned to 203007d190)

Solutions

  1. Supply custom_format_mapping mapping your names to 'audio' and 'text'.
  2. Rename the columns to conventional audio/text names.
  3. Verify the dataset actually contains audio plus transcripts for Spark-TTS training.

Example fix

// before
dataset  # columns: ['speech', 'sentence']
// after
dataset = dataset.rename_column('speech', 'audio').rename_column('sentence', 'text')
Defensive patterns

Strategy: validation

Validate before calling

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

assert bicodec_ready(dataset), "BiCodec needs 'audio' and 'text' columns"

Type guard

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

Try / catch

try:
    ds = trainer._preprocess_bicodec_dataset(dataset, mapping)
except ValueError as e:
    if "BiCodec dataset needs" in str(e):
        dataset = dataset.rename_column('speech', 'audio').rename_column('sentence', 'text')
        ds = trainer._preprocess_bicodec_dataset(dataset, mapping)

Prevention

When it happens

Trigger: Spark-TTS fine-tune with a dataset lacking a text column, lacking audio, or having them under names not recognized by _resolve_audio_columns or provided in custom_format_mapping.

Common situations: Column names like 'speech'/'sentence' unmapped; dataset prepared for a different TTS pipeline; wrong model type routes a non-audio dataset into BiCodec preprocessing.

Related errors

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