iOfficeAI/OfficeCLI · error · ArgumentException

--xml is required for prepend

Error message

--xml is required for prepend

What it means

Thrown when the action is 'prepend' but the xml argument is null. Prepend adds the fragment as the first child of each matched element; without a fragment there is nothing to add. ArgumentException thrown inside the per-node loop.

Source

Thrown at src/officecli/Core/RawXmlHelper.cs:175

                ". No xmlns declarations needed in --xml fragments.");
        }

        int affected = 0;

        foreach (var node in nodes)
        {
            switch (action.ToLowerInvariant())
            {
                case "append":
                    if (xml == null) throw new ArgumentException("--xml is required for append");
                    var appendFragment = ParseFragment(xml, xDoc);
                    foreach (var el in appendFragment)
                        node.Add(el);
                    affected++;
                    break;

                case "prepend":
                    if (xml == null) throw new ArgumentException("--xml is required for prepend");
                    var prependFragment = ParseFragment(xml, xDoc);
                    foreach (var el in prependFragment.AsEnumerable().Reverse())
                        node.AddFirst(el);
                    affected++;
                    break;

                case "insertbefore" or "before":
                    if (xml == null) throw new ArgumentException("--xml is required for insertbefore");
                    RequireParent(node, "insertbefore");
                    var beforeFragment = ParseFragment(xml, xDoc);
                    // AddBeforeSelf lands each element immediately before the
                    // anchor, i.e. AFTER everything inserted so far — forward
                    // iteration preserves source order. (The reverse idiom is
                    // insertafter-only; reversing here flipped a multi-element
                    // fragment, splitting bookmarkStart/End pairs so the id
                    // balancer synthesized a duplicate w:id end marker.)
                    foreach (var el in beforeFragment)
                        node.AddBeforeSelf(el);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Provide a valid XML fragment to prepend as the first child of each matched element.
2. If you meant to add a sibling before the matched element, use 'insertbefore' instead.

Example fix

// before
RawXmlHelper.Execute(root, xpath, "prepend", null);

// after
RawXmlHelper.Execute(root, xpath, "prepend", "<w:pPr><w:pStyle w:val=\"Heading1\"/></w:pPr>");

if (action.Equals("prepend", StringComparison.OrdinalIgnoreCase) && string.IsNullOrEmpty(xml))
    throw new ArgumentException("--xml is required for prepend");

RawXmlHelper.Execute(rootElement, xpath, action, xml);

try
{
    RawXmlHelper.Execute(rootElement, xpath, "prepend", xml);
}
catch (ArgumentException ex) when (ex.Message == "--xml is required for prepend")
{
    Console.Error.WriteLine("Provide an XML fragment to prepend as the first child of matched elements.");
}

When it happens

Trigger: RawXmlHelper.Execute(rootElement, xpath, "prepend", null). XPath matched at least one element, code entered the prepend case, xml == null.

Common situations: Caller invokes raw-set with action=prepend but omits --xml. JSON API caller sends prepend without an xml field. Misunderstanding that prepend requires content.

Related errors

• --xml is required for append
• --xml is required for insertbefore
• --xml is required for insertafter
• --xml is required for replace
• --xml is required for setattr (format: name=value)

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