{"record":{"id":"2dc2671a568f6fa1","repo":"xai-org/grok-build","slug":"agents-invalid-json-e","errorCode":null,"errorMessage":"--agents: invalid JSON: {e}","messagePattern":"--agents: invalid JSON: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-pager/src/headless/cli.rs","lineNumber":217,"sourceCode":"pub(crate) enum ResolvedAgent {\n    FilePath(PathBuf),\n    Name(String),\n}\n\npub(crate) fn resolve_agent_arg(agent: &str) -> ResolvedAgent {\n    let path = std::path::Path::new(agent);\n    if path.exists() && path.is_file() {\n        ResolvedAgent::FilePath(dunce::canonicalize(path).unwrap_or_else(|_| path.to_path_buf()))\n    } else {\n        ResolvedAgent::Name(agent.to_string())\n    }\n}\n\npub(crate) fn parse_cli_agents(\n    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    }","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-pager/src/headless/cli.rs#L199-L235","documentation":"parse_cli_agents parses the --agents CLI argument as a JSON object mapping agent names to their definitions. If the whole string is not valid JSON, the serde error is wrapped as \"--agents: invalid JSON: {e}\". The library throws it so the failure is attributed to the --agents flag rather than some later agent-resolution step.","triggerScenarios":"Passing --agents a value that serde_json::from_str rejects: not JSON at all, an array instead of an object, a truncated/partial map, or shell-mangled quoting (single quotes removed, inner double quotes unescaped).","commonSituations":"Shell quoting problems on Linux/macOS vs Windows; building the flag value by string concatenation in a script; passing a YAML/TOML agent file's contents instead of JSON; passing a file path instead of inline JSON.","solutions":["Validate the argument with jq . (or echo '<value>' | jq) to see the serde-reported syntax error.","Ensure the value is a JSON object {\"name\": {...}, ...}, not an array or path.","Serialize programmatically (jq -n, JSON.stringify, serde_json::json!) and pass via a shell-safe quoted variable or @file if supported.","Single-quote the whole value on POSIX shells to prevent quote stripping."],"exampleFix":"// before\n--agents {\"reviewer\":{\"prompt\":\"review\"}}   // unquoted, shell eats braces\n// after\n--agents '{\"reviewer\":{\"prompt\":\"review\"}}'","handlingStrategy":"validation","validationCode":"fn agents_arg_is_object_map(s: &str) -> bool {\n    serde_json::from_str::<std::collections::HashMap<String, serde_json::Value>>(s).is_ok()\n}\n// guard before invoking run_single_turn with the --agents value","typeGuard":null,"tryCatchPattern":"match parse_cli_agents(&agents_arg) {\n    Ok(agents) => agents,\n    Err(e) if e.to_string().starts_with(\"--agents: invalid JSON\") => {\n        eprintln!(\"--agents must be a JSON object map: {e}\");\n        std::process::exit(2);\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Single-quote the entire --agents value in POSIX shells.","Load large agent maps from a file and validate with jq first.","Never pass a file path or YAML as the --agents value; inline JSON only.","Escape inner double quotes when interpolating the flag from scripts."],"tags":["json","cli","arguments","serde"],"backgroundTag":"invalid-json-syntax","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}