{"record":{"id":"8005e07d6a19317f","repo":"aaif-goose/goose","slug":"model-spec-is-ambiguous-choose-one-of","errorCode":null,"errorMessage":"Model spec '{}' is ambiguous; choose one of: {}","messagePattern":"Model spec '(.+?)' is ambiguous; choose one of: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/goose-local-inference/src/management.rs","lineNumber":733,"sourceCode":"        };\n    }\n\n    if let Ok((repo_id, quantization)) = hf_models::parse_model_spec(&req.spec) {\n        return Ok(model_id_from_repo(&repo_id, &quantization));\n    }\n\n    let variants = hf_models::get_repo_local_variants(&req.spec).await?;\n    let has_llamacpp = variants\n        .iter()\n        .any(|variant| variant.backend_id == \"llamacpp\");\n    let mlx_variants: Vec<_> = variants\n        .iter()\n        .filter(|variant| variant.backend_id == \"mlx\")\n        .collect();\n    if mlx_variants.len() == 1 && !has_llamacpp {\n        Ok(req.spec.clone())\n    } else {\n        anyhow::bail!(\n            \"Model spec '{}' is ambiguous; choose one of: {}\",\n            req.spec,\n            variants\n                .iter()\n                .map(|variant| variant.download_id.as_str())\n                .collect::<Vec<_>>()\n                .join(\", \")\n        )\n    }\n}\n\nfn mark_download_failed(model_id: &str, error: impl std::fmt::Display) {\n    let manager = get_download_manager();\n    let download_id = format!(\"{}-model\", model_id);\n    if manager.get_progress(&download_id).is_none() {\n        manager.set_progress(DownloadProgress {\n            model_id: download_id.clone(),\n            status: DownloadStatus::Failed,","sourceCodeStart":715,"sourceCodeEnd":751,"githubUrl":"https://github.com/aaif-goose/goose/blob/3810898a7447ec3299be72e223d3570a7aabf0ab/crates/goose-local-inference/src/management.rs#L715-L751","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry with one of the exact download_ids printed in the error message (e.g. append ':Q4_K_M').","Call the variants listing API first and let the user/app pick a quantization before download.","For GGUF, prefer the quantization suffix form 'owner/repo:Q4_K_M' up front.","Pick a sensible default quant for your RAM (Q4_K_M is a common middle ground) when automating."],"exampleFix":"// before\nlet req = DownloadRequest { spec: \"Qwen/Qwen2.5-7B\".into(), backend_id: None, variant_id: None, ..Default::default() };\n// -> Model spec 'Qwen/Qwen2.5-7B' is ambiguous; choose one of: ...:Q2_K, ...:Q4_K_M, ...\n\n// after\nlet req = DownloadRequest { spec: \"Qwen/Qwen2.5-7B:Q4_K_M\".into(), backend_id: None, variant_id: None, ..Default::default() };","handlingStrategy":"validation","validationCode":"let variants = list_repo_local_variants(&spec).await?;\nif variants.len() != 1 {\n    let ids: Vec<_> = variants.iter().map(|v| v.download_id.clone()).collect();\n    anyhow::bail!(\"spec '{spec}' is ambiguous; pick one of: {}\", ids.join(\", \"));\n}\nlet req = DownloadRequest { spec: variants[0].download_id.clone(), ..Default::default() };","typeGuard":null,"tryCatchPattern":"match download_model(req).await {\n    Ok(m) => Ok(m),\n    Err(e) if e.to_string().contains(\"is ambiguous\") => {\n        // parse the listed download_ids out of the message and prompt the user to choose\n        prompt_variant_choice(&e.to_string()).await\n    }\n    Err(e) => Err(e),\n}","preventionTips":["Always download by a fully qualified id: 'owner/repo:QUANT' for GGUF, or the exact MLX download_id.","When automating, default to a RAM-appropriate quant (Q4_K_M) instead of a bare repo spec.","Treat the id list in the error message as the canonical set of valid choices."],"tags":["rust","validation","ambiguous","huggingface","quantization","download","local-inference"],"backgroundTag":null,"analyzedSha":"3810898a7447ec3299be72e223d3570a7aabf0ab","analyzedAt":"2026-08-16T10:14:26.282Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}