fishaudio/fish-speech · error · SystemExit

Reference audio file not found: {ref_audio}

Error message

Reference audio file not found: {ref_audio}

What it means

api_client.py converts each reference audio path to bytes via audio_to_bytes; if the file cannot be read (usually because it doesn't exist) the helper returns None and the client exits with SystemExit naming the path.

Source

Thrown at tools/api_client.py:159

    args = parse_args()

    idstr: str | None = args.reference_id
    # priority: ref_id > [{text, audio},...]
    if idstr is None:
        ref_audios = args.reference_audio or []
        ref_texts = args.reference_text or []

        if len(ref_audios) != len(ref_texts):
            raise SystemExit(
                "--reference_audio and --reference_text must be given the same number "
                f"of values, got {len(ref_audios)} audio(s) and {len(ref_texts)} text(s)."
            )

        byte_audios = []
        for ref_audio in ref_audios:
            audio_bytes = audio_to_bytes(ref_audio)
            if audio_bytes is None:
                raise SystemExit(f"Reference audio file not found: {ref_audio}")
            byte_audios.append(audio_bytes)

        ref_texts = [read_ref_text(ref_text) for ref_text in ref_texts]
    else:
        byte_audios = []
        ref_texts = []
        pass  # in api.py

    data = {
        "text": args.text,
        "references": [
            ServeReferenceAudio(audio=ref_audio, text=ref_text)
            for ref_text, ref_audio in zip(ref_texts, byte_audios)
        ],
        "reference_id": idstr,
        "format": args.format,
        "latency": args.latency,
        "max_new_tokens": args.max_new_tokens,

View on GitHub (pinned to befe400174)

Solutions

1. Verify the path exists (ls) before running; use absolute paths
2. Fix typos/extension mismatches (.way vs .wav)
3. Ensure read permission on the file

from pathlib import Path
missing = [a for a in args.reference_audio if not Path(a).is_file()]
assert not missing, f"missing files: {missing}"

When it happens

Trigger: Passing --reference_audio /path/that/does/not/exist.wav, or a path with wrong permissions, or a directory.

Common situations: Typos in paths, relative paths resolved from the wrong CWD, files moved after copy-pasting a command from notes.

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

• --reference_audio and --reference_text must be given the sam
• {i} is not a file or directory
• Audio file not found: {wav_file_path}
• Number of prompt text ({len(prompt_text)}) and prompt audio
• No model weights found in {path_obj}

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