iOfficeAI/OfficeCLI · error · ArgumentException

--xml is required for insertbefore

Error message

--xml is required for insertbefore

What it means

Thrown when the action is 'insertbefore' (or alias 'before') but the xml argument is null. Insertbefore places the fragment as a preceding sibling of each matched element; it additionally calls RequireParent to ensure the matched node has a parent (you cannot insert a sibling before a root element). Without a fragment there is nothing to insert.

Source

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

            {
                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);
                    affected++;
                    break;

                case "insertafter" or "after":
                    if (xml == null) throw new ArgumentException("--xml is required for insertafter");
                    RequireParent(node, "insertafter");
                    var afterFragment = ParseFragment(xml, xDoc);
                    // AddAfterSelf inserts immediately after `node`, so calling it

View on GitHub (pinned to 1ced45e900)

Solutions

1. Provide a valid XML fragment to insert as a preceding sibling of each matched element.
2. If the matched element is the document root, switch to a different action — insertbefore requires a parent node.
3. Use 'insertbefore' for sibling-level insertion; use 'prepend' for child-level insertion (first child).

Example fix

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

// after
RawXmlHelper.Execute(root, xpath, "insertbefore", "<w:p><w:r><w:t>New paragraph</w:t></w:r></w:p>");

var isInsertBefore = action.Equals("insertbefore", StringComparison.OrdinalIgnoreCase)
                     || action.Equals("before", StringComparison.OrdinalIgnoreCase);
if (isInsertBefore && string.IsNullOrEmpty(xml))
    throw new ArgumentException("--xml is required for insertbefore");

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

try
{
    RawXmlHelper.Execute(rootElement, xpath, "insertbefore", xml);
}
catch (ArgumentException ex) when (ex.Message.Contains("--xml is required for insertbefore"))
{
    Console.Error.WriteLine("Provide an XML fragment to insert as a preceding sibling.");
}

When it happens

Trigger: RawXmlHelper.Execute(rootElement, xpath, "insertbefore", null) or RawXmlHelper.Execute(rootElement, xpath, "before", null). XPath matched, code entered the insertbefore/before case, xml == null.

Common situations: Caller invokes raw-set with action=insertbefore but omits --xml. Caller intended 'prepend' (first child) instead of 'insertbefore' (preceding sibling) and is confused about which requires xml. Argument was set conditionally and the condition was false.

Related errors

• --xml is required for append
• --xml is required for prepend
• --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/80b4d7260f12706c. Report an issue: GitHub.