RVC-Boss/GPT-SoVITS · error · ValueError

ref_audio_path cannot be empty, when the reference audio is

Error message

ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio()

What it means

ValueError raised when ref_audio_path is None/empty AND the prompt cache has no previously-set reference (prompt_semantic is None or refer_spec is None/[]). The API allows omitting ref_audio_path only if you already primed the handler with set_ref_audio(); otherwise there is no voice to clone from and inference cannot proceed.

Source

Thrown at GPT_SoVITS/TTS_infer_pack/TTS.py:1125

        # if fragment_interval < 0.01:
        #     fragment_interval = 0.01
        #     print(i18n("分段间隔过小，已自动设置为0.01"))

        no_prompt_text = False
        if prompt_text in [None, ""]:
            no_prompt_text = True

        assert text_lang in self.configs.languages
        if not no_prompt_text:
            assert prompt_lang in self.configs.languages

        if no_prompt_text and self.configs.use_vocoder:
            raise NO_PROMPT_ERROR("prompt_text cannot be empty when using SoVITS_V3")

        if ref_audio_path in [None, ""] and (
            (self.prompt_cache["prompt_semantic"] is None) or (self.prompt_cache["refer_spec"] in [None, []])
        ):
            raise ValueError(
                "ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio()"
            )

        ###### setting reference audio and prompt text preprocessing ########
        t0 = time.perf_counter()
        if (ref_audio_path is not None) and (
            ref_audio_path != self.prompt_cache["ref_audio_path"]
            or (self.is_v2pro and self.prompt_cache["refer_spec"][0][1] is None)
        ):
            if not os.path.exists(ref_audio_path):
                raise ValueError(f"{ref_audio_path} not exists")
            self.set_ref_audio(ref_audio_path)

        aux_ref_audio_paths = aux_ref_audio_paths if aux_ref_audio_paths is not None else []
        paths = set(aux_ref_audio_paths) & set(self.prompt_cache["aux_ref_audio_paths"])
        if not (len(list(paths)) == len(aux_ref_audio_paths) == len(self.prompt_cache["aux_ref_audio_paths"])):
            self.prompt_cache["aux_ref_audio_paths"] = aux_ref_audio_paths
            self.prompt_cache["refer_spec"] = [self.prompt_cache["refer_spec"][0]]

View on GitHub (pinned to d523079fc0)

Solutions

1. Pass a valid ref_audio_path (3-10 s audio plus its prompt_text) in the inference call.
2. Or call handler.set_ref_audio(path) once before running text-only inference requests that omit ref_audio_path.
3. In server code, validate that either ref_audio_path is non-empty or the cache was primed, and return a 4xx with a clear message instead of letting the ValueError escape.

Example fix

# before
audio = handler.run(text="hello", text_lang="en")  # ValueError: ref_audio_path cannot be empty...

# after
handler.set_ref_audio("ref.wav", "reference transcript")
audio = handler.run(text="hello", text_lang="en")  # uses cached reference

has_cached_ref = handler.prompt_cache["prompt_semantic"] is not None and handler.prompt_cache["refer_spec"] not in [None, []]
if not ref_audio_path and not has_cached_ref:
    raise ValueError("provide ref_audio_path or call set_ref_audio() first")

def ready_to_infer(handler, ref_audio_path: str | None) -> bool:
    if ref_audio_path:
        return True
    return handler.prompt_cache["prompt_semantic"] is not None and handler.prompt_cache["refer_spec"] not in [None, []]

When it happens

Trigger: Calling infer_batch/run with ref_audio_path=None or "" on a fresh TTS handler (or one whose cache was invalidated by a model switch) without a prior set_ref_audio() call.

Common situations: API server restarted and a client reuses an old session assuming the reference persists; caller builds the request dict and the ref_audio_path key is accidentally dropped or set to empty string; streaming client sends its first chunk before priming the reference.

Related errors

• 参考音频在3~10秒范围外，请更换！
• {ref_audio_path} not exists
• prompt_text cannot be empty when using SoVITS_V3
• 参考音频在3~10秒范围外，请更换！
• 请输入有效文本

AI-assisted analysis of RVC-Boss/GPT-SoVITS@d523079fc0 (2026-08-15). Data as JSON: /api/errors/6d0fafdb6b42ad89. Report an issue: GitHub.