{"record":{"id":"659bbb7fe7344a8c","repo":"iOfficeAI/OfficeCLI","slug":"xml-is-required-for-prepend","errorCode":null,"errorMessage":"--xml is required for prepend","messagePattern":"--xml is required for prepend","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/RawXmlHelper.cs","lineNumber":175,"sourceCode":"                \". 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);\n                    // AddBeforeSelf lands each element immediately before the\n                    // anchor, i.e. AFTER everything inserted so far — forward\n                    // iteration preserves source order. (The reverse idiom is\n                    // insertafter-only; reversing here flipped a multi-element\n                    // fragment, splitting bookmarkStart/End pairs so the id\n                    // balancer synthesized a duplicate w:id end marker.)\n                    foreach (var el in beforeFragment)\n                        node.AddBeforeSelf(el);","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/RawXmlHelper.cs#L157-L193","documentation":"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.","triggerScenarios":"RawXmlHelper.Execute(rootElement, xpath, \"prepend\", null). XPath matched at least one element, code entered the prepend case, xml == null.","commonSituations":"Caller invokes raw-set with action=prepend but omits --xml. JSON API caller sends prepend without an xml field. Misunderstanding that prepend requires content.","solutions":["Provide a valid XML fragment to prepend as the first child of each matched element.","If you meant to add a sibling before the matched element, use 'insertbefore' instead."],"exampleFix":"// before\nRawXmlHelper.Execute(root, xpath, \"prepend\", null);\n\n// after\nRawXmlHelper.Execute(root, xpath, \"prepend\", \"<w:pPr><w:pStyle w:val=\\\"Heading1\\\"/></w:pPr>\");","handlingStrategy":"validation","validationCode":"if (action.Equals(\"prepend\", StringComparison.OrdinalIgnoreCase) && string.IsNullOrEmpty(xml))\n    throw new ArgumentException(\"--xml is required for prepend\");\n\nRawXmlHelper.Execute(rootElement, xpath, action, xml);","typeGuard":null,"tryCatchPattern":"try\n{\n    RawXmlHelper.Execute(rootElement, xpath, \"prepend\", xml);\n}\ncatch (ArgumentException ex) when (ex.Message == \"--xml is required for prepend\")\n{\n    Console.Error.WriteLine(\"Provide an XML fragment to prepend as the first child of matched elements.\");\n}","preventionTips":["Provide the xml fragment for prepend (first child insertion).","Use 'insertbefore' for sibling-level insertion, not 'prepend'.","Validate action+xml pairs before calling Execute."],"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"}