xai-org/grok-build · error

--agents: failed to parse '{name}': {e}

Error message

--agents: failed to parse '{name}': {e}

What it means

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.

Source

Thrown at crates/codegen/xai-grok-pager/src/headless/cli.rs:232

    json: &str,
) -> anyhow::Result<Vec<xai_grok_shell::agent::config::AgentDefinition>> {
    let map: std::collections::HashMap<String, serde_json::Value> =
        serde_json::from_str(json).map_err(|e| anyhow::anyhow!("--agents: invalid JSON: {e}"))?;
    let mut agents = Vec::with_capacity(map.len());
    for (name, mut value) in map {
        if let serde_json::Value::Object(ref mut obj) = value {
            if !obj.contains_key("promptBody")
                && let Some(prompt) = obj.remove("prompt")
            {
                obj.insert("promptBody".to_string(), prompt);
            }
            obj.entry("name".to_string())
                .or_insert_with(|| serde_json::Value::String(name.clone()));
            obj.entry("description".to_string())
                .or_insert_with(|| serde_json::Value::String(name.clone()));
        }
        let mut def = xai_grok_shell::agent::config::AgentDefinition::from_json(&value)
            .map_err(|e| anyhow::anyhow!("--agents: failed to parse '{name}': {e}"))?;
        def.name = name;
        agents.push(def);
    }
    Ok(agents)
}

pub(crate) fn apply_agent_flag(
    agent: &Option<String>,
    config: &mut xai_grok_shell::agent::config::Config,
) {
    if let Some(agent) = agent {
        match resolve_agent_arg(agent) {
            ResolvedAgent::FilePath(path) => config.agent_profile_path = Some(path),
            ResolvedAgent::Name(name) => config.agent.name = Some(name),
        }
    }
}

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Read the agent name in the message and the serde detail after it for the exact missing/unknown field.
2. Compare that entry against a known-good AgentDefinition and add/fix required fields.
3. Use "prompt" or "promptBody" (the parser auto-fills promptBody from prompt); other aliases are not migrated.
4. Validate the entry JSON against AgentDefinition::from_json standalone before wiring the whole --agents map.

Example fix

// before
{"reviewer":{"description":"reviews code"}}
// after
{"reviewer":{"description":"reviews code","prompt":"Review the code."}}

fn agent_entries_ok(s: &str) -> bool {
    serde_json::from_str::<std::collections::HashMap<String, serde_json::Value>>(s)
        .map(|m| m.values().all(|v| {
            xai_grok_shell::agent::config::AgentDefinition::from_json(v).is_ok()
        }))
        .unwrap_or(false)
}

fn has_prompt_field(v: &serde_json::Value) -> bool {
    v.as_object()
        .map(|o| o.contains_key("prompt") || o.contains_key("promptBody"))
        .unwrap_or(false)
}

match parse_cli_agents(&agents_arg) {
    Ok(agents) => agents,
    Err(e) if e.to_string().starts_with("--agents: failed to parse") => {
        eprintln!("fix the named agent's definition: {e}");
        std::process::exit(2);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to load manifest: {e}
• --json-schema: invalid JSON: {e}
• --prompt-json: {e}
• Invalid JSON: {e}
• Invalid ACP content blocks: {e}

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/68ccd6b8b2faf2d9. Report an issue: GitHub.