{"record":{"id":"9ae9acea99125e1b","repo":"sigoden/aichat","slug":"err-usage","errorCode":null,"errorMessage":"{err}. Usage: {}","messagePattern":"(.+?)\\. Usage: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/config/mod.rs","lineNumber":2474,"sourceCode":"        *self == WorkingMode::Serve\n    }\n}\n\n#[async_recursion::async_recursion]\npub async fn macro_execute(\n    config: &GlobalConfig,\n    name: &str,\n    args: Option<&str>,\n    abort_signal: AbortSignal,\n) -> Result<()> {\n    let macro_value = Config::load_macro(name)?;\n    let (mut new_args, text) = split_args_text(args.unwrap_or_default(), cfg!(windows));\n    if !text.is_empty() {\n        new_args.push(text.to_string());\n    }\n    let variables = macro_value\n        .resolve_variables(&new_args)\n        .map_err(|err| anyhow!(\"{err}. Usage: {}\", macro_value.usage(name)))?;\n    let role = config.read().extract_role();\n    let mut config = config.read().clone();\n    config.temperature = role.temperature();\n    config.top_p = role.top_p();\n    config.use_tools = role.use_tools().clone();\n    config.macro_flag = true;\n    config.model = role.model().clone();\n    config.role = None;\n    config.session = None;\n    config.rag = None;\n    config.agent = None;\n    config.discontinuous_last_message();\n    let config = Arc::new(RwLock::new(config));\n    config.write().macro_flag = true;\n    for step in &macro_value.steps {\n        let command = Macro::interpolate_command(step, &variables);\n        println!(\">> {}\", multiline_text(&command));\n        run_repl_command(&config, abort_signal.clone(), &command).await?;","sourceCodeStart":2456,"sourceCodeEnd":2492,"githubUrl":"https://github.com/sigoden/aichat/blob/82976d349ad97ac9aae0655ad631dace5e2a6385/src/config/mod.rs#L2456-L2492","documentation":"In src/config/mod.rs macro-argument handling, `macro_value.resolve_variables(&new_args)` failed while expanding `$1`-style variables in macro arguments. The library wraps the underlying error with the macro's usage string: `{err}. Usage: {}` so the caller sees how to invoke it correctly.","triggerScenarios":"Running a macro with arguments that don't satisfy its declared variables (missing required positional args, invalid flag syntax, or text split issues) — resolve_variables returns Err and it's mapped to include `macro_value.usage(name)`.","commonSituations":"Invoking `llm --macro NAME` with too few arguments; forgetting to quote an argument containing spaces; Windows argument-splitting quirks with `split_args_text`.","solutions":["Follow the printed `Usage:` line exactly — it shows required arguments/variables.","Quote arguments containing spaces: `llm --macro summarize \"long text here\"`.","Check the macro definition (`$1`, `$2`, flags) and supply every declared variable.","On Windows, mind path backslash/quote handling if the macro expects raw text."],"exampleFix":"// before\nllm --macro translate\nError: missing variable $1. Usage: translate <text>\n\n// after\nllm --macro translate \"hello world\"","handlingStrategy":"validation","validationCode":"// Shell: check argument count against macro usage before invoking\nusage=$(llm --macro mymacro 2>&1 | sed -n 's/.*Usage: //p')\n[[ $# -ge 1 ]] || { echo \"Usage: $usage\"; exit 1; }","typeGuard":null,"tryCatchPattern":"// Rust\nmatch run_macro(name, args) {\n    Err(e) if e.to_string().contains(\"Usage:\") => {\n    eprintln!(\"{e}\"); // usage message is embedded — surface it verbatim\n    }\n    other => other?,\n}","preventionTips":["Quote all arguments containing spaces.","Read the macro's declared variables ($1, $2, flags) before invoking.","Count supplied arguments against the usage line.","Be aware of Windows arg-splitting differences."],"tags":["macro","cli","arguments","usage"],"backgroundTag":"missing-required-argument","analyzedSha":"82976d349ad97ac9aae0655ad631dace5e2a6385","analyzedAt":"2026-09-09T18:33:06.139Z","contentChangedAt":"2026-09-09T18:33:06.139Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}