{"record":{"id":"521c59dcd5c698ea","repo":"iOfficeAI/OfficeCLI","slug":"raw-set-xpath-matched-no-elements-xpath-hint","errorCode":null,"errorMessage":"raw-set: XPath matched no elements: {xpath}. Hint: auto-registered namespace prefixes: {string.Join(\", \", CommonNamespaces.Keys.Order())}. No xmlns declarations needed in --xml fragments.","messagePattern":"raw-set: XPath matched no elements: (.+?)\\. Hint: auto-registered namespace prefixes: (.+?)\\. No xmlns declarations needed in --xml fragments\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/RawXmlHelper.cs","lineNumber":153,"sourceCode":"            case \"replace\":\n            case \"remove\":\n            case \"delete\":\n            case \"setattr\":\n                break;\n            default:\n                throw new ArgumentException($\"Unknown action: {action}. Supported: append, prepend, insertbefore, insertafter, replace, remove, setattr\");\n        }\n\n        var nodes = xDoc.XPathSelectElements(xpath, nsManager).ToList();\n        if (nodes.Count == 0)\n        {\n            // Throw rather than return 0 affected with a stderr nudge: the\n            // stderr line is trivially dropped by pipelines and batch\n            // 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++;","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/RawXmlHelper.cs#L135-L171","documentation":"Thrown when the XPath expression matched zero elements in the target XML. This is a deliberate design choice: RawXmlHelper throws rather than silently returning 0 affected nodes, because a stderr nudge would be trivially dropped by pipelines and batch envelopes, making a typo'd XPath look identical to a successful no-op mutation. The error message lists all auto-registered namespace prefixes so the caller can fix the XPath without guessing.","triggerScenarios":"RawXmlHelper.ExecuteOnXmlString evaluates XPathSelectElements(xpath, nsManager).ToList() and the result count is 0. The XPath didn't match any element in the part's XML — due to a typo, wrong namespace prefix, wrong element name, or a document structure that differs from expectation.","commonSituations":"Namespace prefix in the XPath isn't auto-registered (the hint lists CommonNamespaces.Keys). XPath targets an element that exists in a different part (e.g. querying footnotes.xml XPath against document.xml). Element name typo: //w:pP instead of //w:pPr. Structural mismatch: the document doesn't have the expected nesting. XPath uses a prefix the document doesn't declare.","solutions":["Check the error's hint: it lists all auto-registered namespace prefixes (e.g. w, r, p, mc, a). Use one of those prefixes in your XPath.","Test the XPath against the actual XML: dump the part with `raw-read --part <uri>` and evaluate the XPath against it.","Verify the element name spelling — OOXML names are terse and easily confused (w:pPr vs w:pStyle vs w:p).","If the element should exist but doesn't, the document structure may differ from your assumption — inspect it first with raw-read.","Use namespace-agnostic XPath if the prefix isn't registered: //*[local-name()='pPr'] instead of //w:pPr."],"exampleFix":"// before: wrong namespace prefix not in CommonNamespaces\nRawXmlHelper.Execute(root, \"//mycustom:elem\", \"append\", \"<w:p/>\");\n\n// after: use auto-registered prefix, or local-name fallback\nRawXmlHelper.Execute(root, \"//w:pPr\", \"append\", \"<w:p/>\");\n// or namespace-agnostic:\nRawXmlHelper.Execute(root, \"//*[local-name()='pPr']\", \"append\", \"<w:p/>\");","handlingStrategy":"validation","validationCode":"// Test the XPath against the XML before mutating\nvar testDoc = XDocument.Parse(rootElement.OuterXml);\nvar nsManager = BuildNamespaceManager(testDoc);  // or use CommonNamespaces\nvar matchCount = testDoc.XPathEvaluate(xpath, nsManager) switch\n{\n    IEnumerable<XElement> els => els.Count(),\n    _ => 0\n};\nif (matchCount == 0)\n    Console.Error.WriteLine($\"Warning: XPath '{xpath}' matched 0 elements. Check prefix/element name.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    var affected = RawXmlHelper.Execute(rootElement, xpath, action, xml);\n}\ncatch (ArgumentException ex) when (ex.Message.Contains(\"XPath matched no elements\"))\n{\n    // The XPath didn't match. The error lists auto-registered namespace prefixes.\n    // Use one of those prefixes, or try local-name() XPath.\n    Console.Error.WriteLine(ex.Message);\n    // Fallback: namespace-agnostic XPath\n    var localName = ExtractLocalName(xpath);\n    RawXmlHelper.Execute(rootElement, $\"//*[local-name()='{localName}']\", action, xml);\n}","preventionTips":["Dump the part XML with `raw-read --part <uri>` and test the XPath before mutating.","Use namespace-agnostic XPath (//*[local-name()='...']) when unsure about prefixes.","Read the error hint — it lists all auto-registered CommonNamespaces prefixes.","Verify element name spelling against the OOXML schema (w:pPr not w:pP, etc.)."],"tags":["xml","xpath","openxml","namespace","validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}