iOfficeAI/OfficeCLI · error · ArgumentException

'add-part' command requires 'parent' field. Example: {"comma

Error message

'add-part' command requires 'parent' field. Example: {"command": "add-part", "parent": "/slide[1]", "type": "smartart", "props": {"data": "rId2"}}

What it means

Thrown by the batch 'add-part' command when item.Parent is null or empty. add-part attaches a new package part (chart, smartart, image, …) to a parent element/container, so the attachment point is mandatory. The parent must be an existing, addressable element path.

Source

Thrown at src/officecli/CommandBuilder.cs:1223

            }
            case "raw":
            {
                if (string.IsNullOrEmpty(item.Part))
                    throw new ArgumentException("'raw' command requires 'part' field. Example: {\"command\": \"raw\", \"part\": \"/document\"} (docx), {\"command\": \"raw\", \"part\": \"/presentation\"} (pptx), {\"command\": \"raw\", \"part\": \"/sheet[1]\"} (xlsx)");
                return handler.Raw(item.Part, null, null, null);
            }
            case "raw-set":
            {
                var partPath = item.Part ?? "/document";
                var xpath = item.Xpath ?? "";
                var action = item.Action ?? "";
                handler.RawSet(partPath, xpath, action, item.Xml);
                return $"raw-set {action} applied";
            }
            case "add-part":
            {
                if (string.IsNullOrEmpty(item.Parent))
                    throw new ArgumentException("'add-part' command requires 'parent' field. Example: {\"command\": \"add-part\", \"parent\": \"/slide[1]\", \"type\": \"smartart\", \"props\": {\"data\": \"rId2\"}}");
                if (string.IsNullOrEmpty(item.Type))
                    throw new ArgumentException("'add-part' command requires 'type' field. Supported (pptx): chart, smartart, video, audio, model3d, ole, image, hyperlink, theme.");
                var (relId, partOut) = handler.AddPart(item.Parent, item.Type, props);
                return $"Created {item.Type} part: relId={relId} path={partOut}";
            }
            case "validate":
            {
                var errors = handler.Validate();
                if (errors.Count == 0) return "Validation passed: no errors found.";
                var lines = new List<string> { $"Found {errors.Count} validation error(s):" };
                foreach (var err in errors)
                {
                    lines.Add($"  [{err.ErrorType}] {err.Description}");
                    if (err.Path != null) lines.Add($"    Path: {err.Path}");
                    if (err.Part != null) lines.Add($"    Part: {err.Part}");
                }
                return string.Join("\n", lines);
            }

View on GitHub (pinned to 1ced45e900)

Solutions

1. Add a 'parent' field pointing at the container that owns the new part, e.g. /slide[1].
2. Ensure the parent path exists before add-part (the relationship cannot target a non-existent element).
3. Then also set 'type' and, usually, a 'props' object (the next guard requires type).

Example fix

// before
{"command":"add-part","type":"smartart"}
// after
{"command":"add-part","parent":"/slide[1]","type":"smartart","props":{"data":"rId2"}}

if (string.IsNullOrEmpty(item.Parent))
    throw new ArgumentException("'add-part' requires 'parent', e.g. /slide[1]");

static bool HasAddPartParent(BatchItem i) => !string.IsNullOrEmpty(i.Parent);

try { (relId, part) = Dispatch(item); }
catch (ArgumentException ex) when (ex.Message.Contains("'add-part' command requires 'parent'"))
{ /* resolve a parent path and retry */ }

When it happens

Trigger: A batch item {"command":"add-part","type":"image"} with no 'parent'. A caller that names the parent 'path' or 'container' instead of 'parent'.

Common situations: An agent builds an add-part item and remembers 'type' and 'props' but forgets 'parent'. A caller copies a 'shape' add template (which uses parent/type) but drops parent.

Related errors

• 'add-part' command requires 'type' field. Supported (pptx):
• 'remove' command requires 'path' field. Example: {"command":
• 'swap' command requires 'path' and 'path2' (or 'to') fields.
• 'raw' command requires 'part' field. Example: {"command": "r
• Batch item missing required 'command' field. Valid commands:

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/c4711f5ab3201d62. Report an issue: GitHub.