iOfficeAI/OfficeCLI · error · ArgumentException

--xml is required for append

Error message

--xml is required for append

What it means

Thrown when the action is 'append' but the xml argument (the XML fragment to append) is null. Append adds the fragment as the last child of each matched element; without a fragment there is nothing to add. This is an ArgumentException thrown inside the per-node loop, after XPath has already matched at least one element.

Source

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

            // envelopes, leaving callers with success:true on a no-op. A
            // typo'd xpath then looks indistinguishable from a real
            // mutation. Surface the failure where every consumer
            // (standalone, batch, resident) already handles exceptions.
            throw new ArgumentException(
                $"raw-set: XPath matched no elements: {xpath}. " +
                "Hint: auto-registered namespace prefixes: " +
                string.Join(", ", CommonNamespaces.Keys.Order()) +
                ". 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);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Provide a valid XML fragment as the xml argument: the fragment to append as the last child of each matched element.
2. Ensure the fragment is well-formed XML (it's parsed by ParseFragment).
3. If you intended to remove elements, use action='remove' instead — append is always additive.

Example fix

// before: append called without xml fragment
RawXmlHelper.Execute(root, xpath, "append", null);

// after: provide the fragment to append as last child
RawXmlHelper.Execute(root, xpath, "append", "<w:pPr><w:jc w:val=\"center\"/></w:pPr>");

// Validate that xml is provided for append before calling
if (action.Equals("append", StringComparison.OrdinalIgnoreCase) && string.IsNullOrEmpty(xml))
    throw new ArgumentException("--xml is required for append");

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

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

When it happens

Trigger: RawXmlHelper.Execute(rootElement, xpath, "append", null) — the fourth argument (xml) is null or omitted. XPath matched at least one element (otherwise [391] would have fired first), and the code enters the append case where xml == null.

Common situations: Caller omits the --xml flag when invoking raw-set with action=append. Argument is conditionally built and the condition evaluated to null. JSON API caller sends "action":"append" without an "xml" field. Misunderstanding that append requires content to add.

Related errors

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