iOfficeAI/OfficeCLI · error · ArgumentException

Unknown action: {action}. Supported: append, prepend, insert

Error message

Unknown action: {action}. Supported: append, prepend, insertbefore, insertafter, replace, remove, setattr

What it means

Thrown by RawXmlHelper.ExecuteOnXmlString when the action argument is not one of the supported verbs: append, prepend, insertbefore (alias: before), insertafter (alias: after), replace, remove (alias: delete), setattr. Validation runs BEFORE the XPath is evaluated, so a bad action is never masked by a no-match XPath. Note: aliases 'before', 'after', 'delete' are accepted but not listed in the error message's 'Supported:' text.

Source

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

        // never masked by a no-match xpath. Without this, a typo'd action
        // combined with a stale xpath would batch-report "OK" while doing
        // nothing — the user sees no signal that the action name was wrong.
        var normalizedAction = action.ToLowerInvariant();
        switch (normalizedAction)
        {
            case "append":
            case "prepend":
            case "insertbefore":
            case "before":
            case "insertafter":
            case "after":
            case "replace":
            case "remove":
            case "delete":
            case "setattr":
                break;
            default:
                throw new ArgumentException($"Unknown action: {action}. Supported: append, prepend, insertbefore, insertafter, replace, remove, setattr");
        }

        var nodes = xDoc.XPathSelectElements(xpath, nsManager).ToList();
        if (nodes.Count == 0)
        {
            // Throw rather than return 0 affected with a stderr nudge: the
            // stderr line is trivially dropped by pipelines and batch
            // 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.");
        }

View on GitHub (pinned to 1ced45e900)

Solutions

Use one of the exact action names: append, prepend, insertbefore, insertafter, replace, remove, setattr (case-insensitive). Aliases before/after/delete also work.
Check argument order: Execute(rootElement, xpath, action, xml) — a positional swap of xpath and action produces this error.
For adding content, use 'append' (inside target as last child) or 'insertafter' (after target as sibling).
For removing, use 'remove' or 'delete' (alias). For attribute changes, use 'setattr' with name=value syntax.

Example fix

// before: typo or wrong synonym
RawXmlHelper.Execute(root, xpath, "insert", "<w:p/>");
RawXmlHelper.Execute(root, xpath, "add", "<w:p/>");

// after: correct action name
RawXmlHelper.Execute(root, xpath, "insertafter", "<w:p/>");
RawXmlHelper.Execute(root, xpath, "append", "<w:p/>");

Defensive patterns

Strategy: validation

Validate before calling

// Validate action before calling Execute
static readonly HashSet<string> ValidActions = new()
{
    "append", "prepend", "insertbefore", "before",
    "insertafter", "after", "replace", "remove", "delete", "setattr"
};

if (!ValidActions.Contains(action.ToLowerInvariant()))
    throw new ArgumentException($"Invalid action '{action}'. Supported: {string.Join(", ", ValidActions)}");

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

Type guard

static bool IsValidAction(string action) =>
    action.ToLowerInvariant() is "append" or "prepend" or "insertbefore" or "before"
        or "insertafter" or "after" or "replace" or "remove" or "delete" or "setattr";

Try / catch

try
{
    RawXmlHelper.Execute(rootElement, xpath, action, xml);
}
catch (ArgumentException ex) when (ex.Message.StartsWith("Unknown action"))
{
    Console.Error.WriteLine($"'{action}' is not a valid raw-set action. Use: append, prepend, insertbefore, insertafter, replace, remove, setattr.");
}

Prevention

Validate the action against the known set before calling Execute.
Double-check argument order: Execute(root, xpath, action, xml) — swapping xpath and action triggers this.
Use constants or an enum for action names to prevent typos.

When it happens

Trigger: RawXmlHelper.Execute(rootElement, xpath, action, xml) or RawXmlHelper.Execute(part, xpath, action, xml) is called with an action string that doesn't match any case in the normalization switch. The comparison is case-insensitive (action.ToLowerInvariant()).

Common situations: Typo: 'inserBefore', 'apend', 'setatr'. Using a synonym not in the list: 'add', 'insert', 'modify', 'update', 'change', 'delete_all'. Passing a command name from a different API surface. Accidentally passing the XPath as the action argument (argument order swap).

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/c4754fab613dd5dc. Report an issue: GitHub.