fishaudio/fish-speech · error · FileNotFoundError

Audio file not found: {wav_file_path}

Error message

Audio file not found: {wav_file_path}

What it means

Before creating a reference, add_reference verifies the supplied audio file exists on disk. A missing file raises FileNotFoundError with the given path, so the error is always a path problem on the caller's side, not a library issue.

Source

Thrown at fish_speech/inference_engine/reference_loader.py:214

            wav_file_path: Path to the audio file to copy
            reference_text: Text content for the .lab file

        Raises:
            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)

View on GitHub (pinned to befe400174)

Solutions

  1. Use an absolute path: str(Path(wav).resolve())
  2. Verify the file is fully written/flushed before calling add_reference
  3. Check the path exists in the same process/CWD that runs ReferenceLoader

Example fix

# before
loader.add_reference("my_voice", "ref.wav")  # FileNotFoundError if CWD differs

# after
from pathlib import Path
loader.add_reference("my_voice", str(Path("ref.wav").resolve()))
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
wav = Path(wav_file_path).resolve()
assert wav.is_file(), f"audio file missing: {wav}"

Try / catch

try:
    loader.add_reference(ref_id, wav)
except FileNotFoundError as e:
    raise RuntimeError(f"audio file not found — check path/CWD: {wav_file_path}") from e

Prevention

When it happens

Trigger: Calling add_reference("id", "ref.wav") when the wav path is wrong, relative to a different working directory, or the file hasn't been uploaded/saved yet.

Common situations: Relative paths resolved from a different CWD (server vs CLI), audio file still in a temp upload buffer not yet flushed to disk, or typo'd filenames.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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