iOfficeAI/OfficeCLI · error · ArgumentException

'raw' command requires 'part' field. Example: {"command": "r

Error message

'raw' command requires 'part' field. Example: {"command": "raw", "part": "/document"} (docx), {"command": "raw", "part": "/presentation"} (pptx), {"command": "raw", "part": "/sheet[1]"} (xlsx)

What it means

Thrown by the batch 'raw' command when item.Part is null or empty. The raw command reads a raw XML part from the package by its part path (e.g. /document, /presentation, /sheet[1]), so a missing target is a hard error. The message lists the per-document-type root part examples.

Source

Thrown at src/officecli/CommandBuilder.cs:1209

                }
                if (mode.ToLowerInvariant() is "svg" or "g" && handler is OfficeCli.Handlers.PowerPointHandler pptSvg)
                {
                    return pptSvg.ViewAsSvg(1);
                }
                return mode.ToLowerInvariant() switch
                {
                    "text" or "t" => handler.ViewAsText(null, null, null, null),
                    "annotated" or "a" => handler.ViewAsAnnotated(null, null, null, null),
                    "outline" or "o" => handler.ViewAsOutline(),
                    "stats" or "s" => handler.ViewAsStats(),
                    "issues" or "i" => OfficeCli.Core.OutputFormatter.FormatIssues(handler.ViewAsIssues(null, null), format),
                    _ => $"Unknown mode: {mode}"
                };
            }
            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}";

View on GitHub (pinned to 1ced45e900)

Solutions

1. Add a 'part' field with the package part path: /document (docx), /presentation (pptx), /sheet[1] (xlsx).
2. Use 'view' or 'get' if you actually wanted a logical element rather than the raw XML part.
3. Run 'raw' once with a known part to discover the package structure, then target sub-parts.

Example fix

// before
{"command":"raw"}
// after
{"command":"raw","part":"/document"}

if (string.IsNullOrEmpty(item.Part))
    throw new ArgumentException("'raw' requires 'part', e.g. /document (docx), /presentation (pptx), /sheet[1] (xlsx)");

static bool HasRawPart(BatchItem i) => !string.IsNullOrEmpty(i.Part);

try { result = Dispatch(item); }
catch (ArgumentException ex) when (ex.Message.Contains("'raw' command requires 'part'"))
{ /* ask caller for the part path */ }

When it happens

Trigger: A batch item {"command":"raw"} with no 'part' field, or a caller that puts the part under 'path' instead of 'part'.

Common situations: An agent confuses 'raw' with 'get' (which uses path) and omits 'part'. A caller assumes a default part exists — there is none; the field is mandatory.

Related errors

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

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