{"record":{"id":"68ccd6b8b2faf2d9","repo":"xai-org/grok-build","slug":"agents-failed-to-parse-name-e","errorCode":null,"errorMessage":"--agents: failed to parse '{name}': {e}","messagePattern":"--agents: failed to parse '(.+?)': (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-pager/src/headless/cli.rs","lineNumber":232,"sourceCode":"    json: &str,\n) -> anyhow::Result<Vec<xai_grok_shell::agent::config::AgentDefinition>> {\n    let map: std::collections::HashMap<String, serde_json::Value> =\n        serde_json::from_str(json).map_err(|e| anyhow::anyhow!(\"--agents: invalid JSON: {e}\"))?;\n    let mut agents = Vec::with_capacity(map.len());\n    for (name, mut value) in map {\n        if let serde_json::Value::Object(ref mut obj) = value {\n            if !obj.contains_key(\"promptBody\")\n                && let Some(prompt) = obj.remove(\"prompt\")\n            {\n                obj.insert(\"promptBody\".to_string(), prompt);\n            }\n            obj.entry(\"name\".to_string())\n                .or_insert_with(|| serde_json::Value::String(name.clone()));\n            obj.entry(\"description\".to_string())\n                .or_insert_with(|| serde_json::Value::String(name.clone()));\n        }\n        let mut def = xai_grok_shell::agent::config::AgentDefinition::from_json(&value)\n            .map_err(|e| anyhow::anyhow!(\"--agents: failed to parse '{name}': {e}\"))?;\n        def.name = name;\n        agents.push(def);\n    }\n    Ok(agents)\n}\n\npub(crate) fn apply_agent_flag(\n    agent: &Option<String>,\n    config: &mut xai_grok_shell::agent::config::Config,\n) {\n    if let Some(agent) = agent {\n        match resolve_agent_arg(agent) {\n            ResolvedAgent::FilePath(path) => config.agent_profile_path = Some(path),\n            ResolvedAgent::Name(name) => config.agent.name = Some(name),\n        }\n    }\n}\n","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-pager/src/headless/cli.rs#L214-L250","documentation":"After top-level JSON parsing succeeds, parse_cli_agents deserializes each entry's value into AgentDefinition via AgentDefinition::from_json. When a specific agent's definition does not match the schema, the error is wrapped as \"--agents: failed to parse '{name}': {e}\", naming the offending agent. Other agents in the map are unaffected conceptually — the whole call fails, but the message pinpoints the bad entry.","triggerScenarios":"An entry value in the --agents map lacks required AgentDefinition fields, has wrong field types, or contains unknown fields rejected by deserialization — any from_json failure for one map entry.","commonSituations":"Missing required fields like prompt/promptBody on one agent; copying an agent definition from a config file with a different schema/version; field typos (promt, prompt_body) — note parse_cli_agents only migrates \"prompt\" to \"promptBody\" automatically.","solutions":["Read the agent name in the message and the serde detail after it for the exact missing/unknown field.","Compare that entry against a known-good AgentDefinition and add/fix required fields.","Use \"prompt\" or \"promptBody\" (the parser auto-fills promptBody from prompt); other aliases are not migrated.","Validate the entry JSON against AgentDefinition::from_json standalone before wiring the whole --agents map."],"exampleFix":"// before\n{\"reviewer\":{\"description\":\"reviews code\"}}\n// after\n{\"reviewer\":{\"description\":\"reviews code\",\"prompt\":\"Review the code.\"}}","handlingStrategy":"validation","validationCode":"fn agent_entries_ok(s: &str) -> bool {\n    serde_json::from_str::<std::collections::HashMap<String, serde_json::Value>>(s)\n        .map(|m| m.values().all(|v| {\n            xai_grok_shell::agent::config::AgentDefinition::from_json(v).is_ok()\n        }))\n        .unwrap_or(false)\n}","typeGuard":"fn has_prompt_field(v: &serde_json::Value) -> bool {\n    v.as_object()\n        .map(|o| o.contains_key(\"prompt\") || o.contains_key(\"promptBody\"))\n        .unwrap_or(false)\n}","tryCatchPattern":"match parse_cli_agents(&agents_arg) {\n    Ok(agents) => agents,\n    Err(e) if e.to_string().starts_with(\"--agents: failed to parse\") => {\n        eprintln!(\"fix the named agent's definition: {e}\");\n        std::process::exit(2);\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Give every agent entry a \"prompt\" (auto-migrated to promptBody) or \"promptBody\" field.","Copy definitions from a known-good AgentDefinition example.","Check agent schemas after upgrading the crate; field requirements can change.","Validate each entry with AgentDefinition::from_json before composing the map."],"tags":["json","schema","cli","agents"],"backgroundTag":"schema-validation-failed","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}