fishaudio/fish-speech · error · ValueError

Unsupported audio format: {audio_path.suffix}. Supported for

Error message

Unsupported audio format: {audio_path.suffix}. Supported formats: {', '.join(AUDIO_EXTENSIONS)}

What it means

add_reference only accepts audio files whose extension is in AUDIO_EXTENSIONS (checked case-insensitively). Any other suffix raises ValueError listing the supported formats, preventing the loader from ingesting formats its decoder backend can't handle.

Source

Thrown at fish_speech/inference_engine/reference_loader.py:218

            FileExistsError: If the reference ID already exists
            FileNotFoundError: If the audio file doesn't exist
            OSError: If file operations fail
        """
        self._validate_id(id)

        # Check if reference already exists
        ref_dir = Path("references") / id
        if ref_dir.exists():
            raise FileExistsError(f"Reference ID '{id}' already exists")

        # Check if audio file exists
        audio_path = Path(wav_file_path)
        if not audio_path.exists():
            raise FileNotFoundError(f"Audio file not found: {wav_file_path}")

        # Validate audio file extension
        if audio_path.suffix.lower() not in AUDIO_EXTENSIONS:
            raise ValueError(
                f"Unsupported audio format: {audio_path.suffix}. Supported formats: {', '.join(AUDIO_EXTENSIONS)}"
            )

        try:
            # Create reference directory
            ref_dir.mkdir(parents=True, exist_ok=False)

            # Determine the target audio filename with original extension
            target_audio_path = ref_dir / f"sample{audio_path.suffix}"

            # Copy audio file
            import shutil

            shutil.copy2(audio_path, target_audio_path)

            # Create .lab file
            lab_path = ref_dir / "sample.lab"
            with open(lab_path, "w", encoding="utf-8") as f:

View on GitHub (pinned to befe400174)

Solutions

Convert the file to a supported format first, e.g. `ffmpeg -i in.ogg out.wav`
Rename files so the true extension matches the content and is in AUDIO_EXTENSIONS
Check AUDIO_EXTENSIONS (imported in reference_loader.py) for the exact accepted list before ingestion

Example fix

# before
loader.add_reference("my_voice", "voice.ogg")  # ValueError

# after
# ffmpeg -i voice.ogg voice.wav
loader.add_reference("my_voice", "voice.wav")

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
AUDIO_EXT = {".wav", ".mp3", ".flac", ".ogg", ".m4a"}  # mirror AUDIO_EXTENSIONS
if Path(wav).suffix.lower() not in AUDIO_EXT:
    raise ValueError(f"convert first: ffmpeg -i {wav} out.wav")

Type guard

from pathlib import Path

def is_supported_audio(path: str, supported: set[str]) -> bool:
    return Path(path).suffix.lower() in supported

Try / catch

try:
    loader.add_reference(ref_id, wav)
except ValueError as e:
    if "Unsupported audio format" in str(e):
        wav = convert_to_wav(wav)  # e.g. via ffmpeg
        loader.add_reference(ref_id, wav)
    else:
        raise

Prevention

Normalize all uploads to wav/flac at ingest time with ffmpeg
Import AUDIO_EXTENSIONS from the library and validate against it rather than a hardcoded list

When it happens

Trigger: Calling add_reference with e.g. "clip.mp4", "audio.ogg", or a file with no extension; or a double extension like "a.wav.orig" where suffix is ".orig".

Common situations: Uploading raw phone recordings (.m4a/.ogg/.opus) directly without converting, or renamed/temp files whose extension no longer reflects the content.

Related errors

AI-assisted analysis of fishaudio/fish-speech@befe400174 (2026-08-27). Data as JSON: /api/errors/6b4a1e3acaa90faa. Report an issue: GitHub.