{"record":{"id":"ee57dcf0c27f5680","repo":"iOfficeAI/OfficeCLI","slug":"xml-is-required-for-append","errorCode":null,"errorMessage":"--xml is required for append","messagePattern":"--xml is required for append","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/RawXmlHelper.cs","lineNumber":167,"sourceCode":"            // envelopes, leaving callers with success:true on a no-op. A\n            // typo'd xpath then looks indistinguishable from a real\n            // mutation. Surface the failure where every consumer\n            // (standalone, batch, resident) already handles exceptions.\n            throw new ArgumentException(\n                $\"raw-set: XPath matched no elements: {xpath}. \" +\n                \"Hint: auto-registered namespace prefixes: \" +\n                string.Join(\", \", CommonNamespaces.Keys.Order()) +\n                \". No xmlns declarations needed in --xml fragments.\");\n        }\n\n        int affected = 0;\n\n        foreach (var node in nodes)\n        {\n            switch (action.ToLowerInvariant())\n            {\n                case \"append\":\n                    if (xml == null) throw new ArgumentException(\"--xml is required for append\");\n                    var appendFragment = ParseFragment(xml, xDoc);\n                    foreach (var el in appendFragment)\n                        node.Add(el);\n                    affected++;\n                    break;\n\n                case \"prepend\":\n                    if (xml == null) throw new ArgumentException(\"--xml is required for prepend\");\n                    var prependFragment = ParseFragment(xml, xDoc);\n                    foreach (var el in prependFragment.AsEnumerable().Reverse())\n                        node.AddFirst(el);\n                    affected++;\n                    break;\n\n                case \"insertbefore\" or \"before\":\n                    if (xml == null) throw new ArgumentException(\"--xml is required for insertbefore\");\n                    RequireParent(node, \"insertbefore\");\n                    var beforeFragment = ParseFragment(xml, xDoc);","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/RawXmlHelper.cs#L149-L185","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide a valid XML fragment as the xml argument: the fragment to append as the last child of each matched element.","Ensure the fragment is well-formed XML (it's parsed by ParseFragment).","If you intended to remove elements, use action='remove' instead — append is always additive."],"exampleFix":"// before: append called without xml fragment\nRawXmlHelper.Execute(root, xpath, \"append\", null);\n\n// after: provide the fragment to append as last child\nRawXmlHelper.Execute(root, xpath, \"append\", \"<w:pPr><w:jc w:val=\\\"center\\\"/></w:pPr>\");","handlingStrategy":"validation","validationCode":"// Validate that xml is provided for append before calling\nif (action.Equals(\"append\", StringComparison.OrdinalIgnoreCase) && string.IsNullOrEmpty(xml))\n    throw new ArgumentException(\"--xml is required for append\");\n\nRawXmlHelper.Execute(rootElement, xpath, action, xml);","typeGuard":null,"tryCatchPattern":"try\n{\n    RawXmlHelper.Execute(rootElement, xpath, \"append\", xml);\n}\ncatch (ArgumentException ex) when (ex.Message == \"--xml is required for append\")\n{\n    Console.Error.WriteLine(\"Provide an XML fragment to append as the last child of matched elements.\");\n}","preventionTips":["Always provide the xml fragment for all mutation actions except 'remove'/'delete'.","Build a validation layer that checks action+xml requirements before calling Execute.","Use 'remove' if you intended deletion, not 'append'."],"tags":["xml","xpath","openxml","argument","raw-set"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}