Hmbown/CodeWhale · error · anyhow::Error

Model ' ' requires a voice design prompt. Pass…

Error message

Model '{model}' requires a voice design prompt. Pass --voice-prompt or --instruction.

What it means

Xiaomi MiMo 'voicedesign' speech models require a voice design instruction (natural-language prompt describing the voice). If the resolved model name contains 'voicedesign' and no instruction was provided, the client bails pointing at the --voice-prompt / --instruction flags.

Solutions

Pass --voice-prompt (or --instruction) with a non-empty voice description when using a voicedesign model.
Ensure the instruction is not whitespace-only — it is trimmed and empty strings are treated as absent.
Use a non-voicedesign model if you don't need voice design.

Example fix

# before
codewhale tts --model milivo-voicedesign "hello"

# after
codewhale tts --model milivo-voicedesign --voice-prompt "warm, calm male narrator" "hello"

Defensive patterns

Strategy: validation

Validate before calling

fn requires_instruction(model: &str) -> bool { model.to_ascii_lowercase().contains("voicedesign") }
if requires_instruction(&req.model) && req.instruction.as_deref().unwrap_or("").trim().is_empty() {
    return Err(anyhow::anyhow!("voicedesign model requires --voice-prompt"));
}

Try / catch

match result {
    Err(e) if e.to_string().contains("requires a voice design prompt") => {
        eprintln!("Add --voice-prompt \"<voice description>\" when using a voicedesign model");
    }
    r => r?,
}

Prevention

Require --voice-prompt in the CLI parser whenever the model name contains voicedesign.
Trim instruction inputs before sending; whitespace-only counts as missing.
Document voicedesign model requirements in help text.

When it happens

Trigger: Requesting speech synthesis with a model whose lowercased name contains 'voicedesign' while `request.instruction` is None or whitespace after trim/filter.

Common situations: Selecting a voicedesign model but omitting the prompt flags in the CLI; a script templating the model but not the instruction; whitespace-only instruction filtered out by the trim check.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/3071249bca7be251. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/client.rs:3355

        }

        let audio_format = normalize_audio_format(&request.audio_format);
        let model = self.wire_model_for_route(&model);
        let model_lower = model.to_ascii_lowercase();
        let instruction = request
            .instruction
            .as_deref()
            .map(str::trim)
            .filter(|value| !value.is_empty());
        let voice = request
            .voice
            .as_deref()
            .map(str::trim)
            .filter(|value| !value.is_empty())
            .map(str::to_string);

        if model_lower.contains("voicedesign") && instruction.is_none() {
            anyhow::bail!(
                "Model '{model}' requires a voice design prompt. Pass --voice-prompt or --instruction."
            );
        }
        if model_lower.contains("voiceclone") && voice.is_none() {
            anyhow::bail!(
                "Model '{model}' requires cloned voice data. Pass --clone-voice <mp3|wav> or --voice <data-uri>."
            );
        }

        let mut audio = json!({
            "format": audio_format.clone(),
        });
        if let Some(voice) = voice.as_deref() {
            audio["voice"] = json!(voice);
        }

        let body = build_speech_synthesis_body(&model, &text, instruction, audio);

View on GitHub (pinned to 73e0f67d83)