{"record":{"id":"6d0fafdb6b42ad89","repo":"RVC-Boss/GPT-SoVITS","slug":"ref-audio-path-cannot-be-empty-when-the-reference","errorCode":null,"errorMessage":"ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio()","messagePattern":"ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio\\(\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"GPT_SoVITS/TTS_infer_pack/TTS.py","lineNumber":1125,"sourceCode":"        # if fragment_interval < 0.01:\n        #     fragment_interval = 0.01\n        #     print(i18n(\"分段间隔过小，已自动设置为0.01\"))\n\n        no_prompt_text = False\n        if prompt_text in [None, \"\"]:\n            no_prompt_text = True\n\n        assert text_lang in self.configs.languages\n        if not no_prompt_text:\n            assert prompt_lang in self.configs.languages\n\n        if no_prompt_text and self.configs.use_vocoder:\n            raise NO_PROMPT_ERROR(\"prompt_text cannot be empty when using SoVITS_V3\")\n\n        if ref_audio_path in [None, \"\"] and (\n            (self.prompt_cache[\"prompt_semantic\"] is None) or (self.prompt_cache[\"refer_spec\"] in [None, []])\n        ):\n            raise ValueError(\n                \"ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio()\"\n            )\n\n        ###### setting reference audio and prompt text preprocessing ########\n        t0 = time.perf_counter()\n        if (ref_audio_path is not None) and (\n            ref_audio_path != self.prompt_cache[\"ref_audio_path\"]\n            or (self.is_v2pro and self.prompt_cache[\"refer_spec\"][0][1] is None)\n        ):\n            if not os.path.exists(ref_audio_path):\n                raise ValueError(f\"{ref_audio_path} not exists\")\n            self.set_ref_audio(ref_audio_path)\n\n        aux_ref_audio_paths = aux_ref_audio_paths if aux_ref_audio_paths is not None else []\n        paths = set(aux_ref_audio_paths) & set(self.prompt_cache[\"aux_ref_audio_paths\"])\n        if not (len(list(paths)) == len(aux_ref_audio_paths) == len(self.prompt_cache[\"aux_ref_audio_paths\"])):\n            self.prompt_cache[\"aux_ref_audio_paths\"] = aux_ref_audio_paths\n            self.prompt_cache[\"refer_spec\"] = [self.prompt_cache[\"refer_spec\"][0]]","sourceCodeStart":1107,"sourceCodeEnd":1143,"githubUrl":"https://github.com/RVC-Boss/GPT-SoVITS/blob/d523079fc05d9a8028d6085bffe4a2757c32abb6/GPT_SoVITS/TTS_infer_pack/TTS.py#L1107-L1143","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a valid ref_audio_path (3-10 s audio plus its prompt_text) in the inference call.","Or call handler.set_ref_audio(path) once before running text-only inference requests that omit ref_audio_path.","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."],"exampleFix":"# before\naudio = handler.run(text=\"hello\", text_lang=\"en\")  # ValueError: ref_audio_path cannot be empty...\n\n# after\nhandler.set_ref_audio(\"ref.wav\", \"reference transcript\")\naudio = handler.run(text=\"hello\", text_lang=\"en\")  # uses cached reference","handlingStrategy":"validation","validationCode":"has_cached_ref = handler.prompt_cache[\"prompt_semantic\"] is not None and handler.prompt_cache[\"refer_spec\"] not in [None, []]\nif not ref_audio_path and not has_cached_ref:\n    raise ValueError(\"provide ref_audio_path or call set_ref_audio() first\")","typeGuard":"def ready_to_infer(handler, ref_audio_path: str | None) -> bool:\n    if ref_audio_path:\n        return True\n    return handler.prompt_cache[\"prompt_semantic\"] is not None and handler.prompt_cache[\"refer_spec\"] not in [None, []]","tryCatchPattern":null,"preventionTips":["Prime the handler with set_ref_audio() immediately after model load, not lazily per request.","Make ref_audio_path a required API field unless a session reference was explicitly set.","Re-prime the cache after any model (sovits/gpt) switch — switching invalidates the reference."],"tags":["reference-audio","validation","tts","api-misuse"],"backgroundTag":null,"analyzedSha":"d523079fc05d9a8028d6085bffe4a2757c32abb6","analyzedAt":"2026-08-15T01:06:46.402Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}