fishaudio/fish-speech · error · SystemExit

Reference audio file not found

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.

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
Defensive patterns

Strategy: validation

Validate before calling

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}"

Prevention

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

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

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