{"record":{"id":"3a63d4459dfa4dc0","repo":"RVC-Boss/GPT-SoVITS","slug":"prompt-text-cannot-be-empty-when-using-sovits-v3","errorCode":null,"errorMessage":"prompt_text cannot be empty when using SoVITS_V3","messagePattern":"prompt_text cannot be empty when using SoVITS_V3","errorType":"validation","errorClass":"NO_PROMPT_ERROR","httpStatus":null,"severity":"error","filePath":"GPT_SoVITS/TTS_infer_pack/TTS.py","lineNumber":1120,"sourceCode":"            print(i18n(\"当开启并行推理模式时，SoVits V3/4模型不支持分桶处理，已自动关闭分桶处理\"))\n            split_bucket = False\n        else:\n            print(i18n(\"分桶处理模式已关闭\"))\n\n        # 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","sourceCodeStart":1102,"sourceCodeEnd":1138,"githubUrl":"https://github.com/RVC-Boss/GPT-SoVITS/blob/d523079fc05d9a8028d6085bffe4a2757c32abb6/GPT_SoVITS/TTS_infer_pack/TTS.py#L1102-L1138","documentation":"Raised as NO_PROMPT_ERROR when the inference call has no prompt text while the loaded model is SoVITS v2-Pro (configs.use_vocoder is True). The v2Pro vocoder path conditions generation on prompt text tokens; without them the vocoder has no linguistic anchor for the reference, so inference is refused rather than allowed to produce garbage.","triggerScenarios":"Calling infer_batch (or the TTS.run wrapper) with prompt_text=None or \"\" while configs.use_vocoder is True — i.e. a v2Pro sovits model is loaded and the caller tries the 'ref_free' (no prompt text) mode that works for v1/v2.","commonSituations":"User upgrades to a v2Pro model but keeps an old script/preset that omitted prompt text; webui opened in free-reference mode with a Pro model selected; API request built without prompt_text field.","solutions":["Supply the transcript of the reference audio as prompt_text (and matching prompt_lang) whenever a v2Pro/vocoder model is loaded.","If you must run without prompt text, switch back to a non-Pro sovits model (v1/v2/v3/v4 checkpoint without the Pro vocoder path).","In API wrappers, make prompt_text a required field when configs.use_vocoder is True and validate before dispatch."],"exampleFix":"# before\naudio = handler.run(text=\"你好\", text_lang=\"zh\", ref_audio_path=\"ref.wav\")  # NO_PROMPT_ERROR\n\n# after\naudio = handler.run(\n    text=\"你好\", text_lang=\"zh\",\n    ref_audio_path=\"ref.wav\",\n    prompt_text=\"这是参考音频的文字内容\", prompt_lang=\"zh\",  # required for v2Pro\n)","handlingStrategy":"validation","validationCode":"if handler.configs.use_vocoder and not (prompt_text or \"\").strip():\n    raise ValueError(\"prompt_text is required for SoVITS v2Pro models\")","typeGuard":"def requires_prompt_text(handler) -> bool:\n    \"\"\"v2Pro/vocoder models cannot run without the reference transcript.\"\"\"\n    return bool(getattr(handler.configs, \"use_vocoder\", False))","tryCatchPattern":null,"preventionTips":["Treat prompt_text as mandatory whenever a Pro/vocoder model is loaded.","Store the transcript alongside every reference audio file (e.g. ref.wav + ref.txt) so it's never lost.","Validate request payloads in API servers against the loaded model's requirements."],"tags":["prompt-text","v2pro","vocoder","tts","validation"],"backgroundTag":null,"analyzedSha":"d523079fc05d9a8028d6085bffe4a2757c32abb6","analyzedAt":"2026-08-15T01:06:46.402Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}