aaif-goose/goose · error

Model spec '{}' is ambiguous; choose one of: {}

Error message

Model spec '{}' is ambiguous; choose one of: {}

What it means

When a download spec carries no explicit backend or quantization, goose queries HuggingFace for the repo's local variants. If exactly one MLX variant exists and no llama.cpp variant, the spec resolves as-is; otherwise it bails 'Model spec ... is ambiguous' and lists the eligible download_ids. The ids in the message are the valid choices — typically 'owner/repo:QUANT' GGUF variants and/or MLX entries.

Source

Thrown at crates/goose-local-inference/src/management.rs:733

        };
    }

    if let Ok((repo_id, quantization)) = hf_models::parse_model_spec(&req.spec) {
        return Ok(model_id_from_repo(&repo_id, &quantization));
    }

    let variants = hf_models::get_repo_local_variants(&req.spec).await?;
    let has_llamacpp = variants
        .iter()
        .any(|variant| variant.backend_id == "llamacpp");
    let mlx_variants: Vec<_> = variants
        .iter()
        .filter(|variant| variant.backend_id == "mlx")
        .collect();
    if mlx_variants.len() == 1 && !has_llamacpp {
        Ok(req.spec.clone())
    } else {
        anyhow::bail!(
            "Model spec '{}' is ambiguous; choose one of: {}",
            req.spec,
            variants
                .iter()
                .map(|variant| variant.download_id.as_str())
                .collect::<Vec<_>>()
                .join(", ")
        )
    }
}

fn mark_download_failed(model_id: &str, error: impl std::fmt::Display) {
    let manager = get_download_manager();
    let download_id = format!("{}-model", model_id);
    if manager.get_progress(&download_id).is_none() {
        manager.set_progress(DownloadProgress {
            model_id: download_id.clone(),
            status: DownloadStatus::Failed,

View on GitHub (pinned to 3810898a74)

Solutions

1. Retry with one of the exact download_ids printed in the error message (e.g. append ':Q4_K_M').
2. Call the variants listing API first and let the user/app pick a quantization before download.
3. For GGUF, prefer the quantization suffix form 'owner/repo:Q4_K_M' up front.
4. Pick a sensible default quant for your RAM (Q4_K_M is a common middle ground) when automating.

Example fix

// before
let req = DownloadRequest { spec: "Qwen/Qwen2.5-7B".into(), backend_id: None, variant_id: None, ..Default::default() };
// -> Model spec 'Qwen/Qwen2.5-7B' is ambiguous; choose one of: ...:Q2_K, ...:Q4_K_M, ...

// after
let req = DownloadRequest { spec: "Qwen/Qwen2.5-7B:Q4_K_M".into(), backend_id: None, variant_id: None, ..Default::default() };

let variants = list_repo_local_variants(&spec).await?;
if variants.len() != 1 {
    let ids: Vec<_> = variants.iter().map(|v| v.download_id.clone()).collect();
    anyhow::bail!("spec '{spec}' is ambiguous; pick one of: {}", ids.join(", "));
}
let req = DownloadRequest { spec: variants[0].download_id.clone(), ..Default::default() };

match download_model(req).await {
    Ok(m) => Ok(m),
    Err(e) if e.to_string().contains("is ambiguous") => {
        // parse the listed download_ids out of the message and prompt the user to choose
        prompt_variant_choice(&e.to_string()).await
    }
    Err(e) => Err(e),
}

When it happens

Trigger: Downloading a bare repo spec (e.g. "Qwen/Qwen2.5-7B") where the repo has 2+ MLX variants, or any GGUF/llamacpp variant alongside MLX. Requires network access since get_repo_local_variants hits HuggingFace first.

Common situations: Users pasting a HuggingFace repo URL/name without a quant; agents guessing specs; repos like 'bartowski/...' reuploads that carry many quants so the single-MLX shortcut never applies.

Related errors

• llama.cpp model '{}' is missing a quantization
• MLX model {} has no downloadable files
• Unknown local inference backend '{}'
• Download failed after {} retries: {}
• Failed to download: HTTP {}

AI-assisted analysis of aaif-goose/goose@3810898a74 (2026-08-16). Data as JSON: /api/errors/8005e07d6a19317f. Report an issue: GitHub.