iOfficeAI/OfficeCLI · error · InvalidOperationException

swap not supported for this document type

Error message

swap not supported for this document type

What it means

Thrown by the batch 'swap' command when the active document handler is neither PowerPointHandler, WordHandler, nor ExcelHandler. Swap is only implemented for those three document types; any other handler type falls to the default switch arm. It is an InvalidOperationException (not a CliException) because it reflects a capability gap, not malformed input.

Source

Thrown at src/officecli/CommandBuilder.cs:1176

                var resultPath = handler.Move(path, item.To, movePos, props.Count > 0 ? props : null);
                return $"Moved to {resultPath}";
            }
            case "swap":
            {
                // Second element: accept `path2` (canonical — the single-command
                // MCP tool and the CLI `swap path1 path2` both use it) or the
                // legacy `to`. Before path2 was carried, an agent that learned
                // swap from the single command produced a batch item that
                // silently failed the path-presence check below.
                var swapTo = !string.IsNullOrEmpty(item.Path2) ? item.Path2 : item.To;
                if (string.IsNullOrEmpty(item.Path) || string.IsNullOrEmpty(swapTo))
                    throw new ArgumentException("'swap' command requires 'path' and 'path2' (or 'to') fields. Example: {\"command\": \"swap\", \"path\": \"/slide[1]\", \"path2\": \"/slide[2]\"}");
                var (p1, p2) = handler switch
                {
                    OfficeCli.Handlers.PowerPointHandler ppt => ppt.Swap(item.Path, swapTo),
                    OfficeCli.Handlers.WordHandler word => word.Swap(item.Path, swapTo),
                    OfficeCli.Handlers.ExcelHandler excel => excel.Swap(item.Path, swapTo),
                    _ => throw new InvalidOperationException("swap not supported for this document type")
                };
                return $"Swapped {p1} <-> {p2}";
            }
            case "view":
            {
                var mode = item.Mode ?? "text";
                if (mode.ToLowerInvariant() is "html" or "h")
                {
                    if (handler is OfficeCli.Handlers.PowerPointHandler pptH)
                        return pptH.ViewAsHtml();
                    if (handler is OfficeCli.Handlers.ExcelHandler excelH)
                        return excelH.ViewAsHtml();
                    if (handler is OfficeCli.Handlers.WordHandler wordH)
                        return wordH.ViewAsHtml();
                }
                if (mode.ToLowerInvariant() is "svg" or "g" && handler is OfficeCli.Handlers.PowerPointHandler pptSvg)
                {
                    return pptSvg.ViewAsSvg(1);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Confirm the document is a .pptx, .docx, or .xlsx — only those support swap.
2. If you must reorder elements in an unsupported type, use 'move' (move to index/before/after) instead of swap.
3. Drop the swap item from batches sent to unsupported document types.

Example fix

// before — swap item on an unsupported handler
{"command":"swap","path":"/a[1]","path2":"/a[2]"}
// after — reorder with move instead
{"command":"move","path":"/a[1]","to":"/a","index":2}

// only issue swap for handlers that implement it
var swapCapable = handler is PowerPointHandler or WordHandler or ExcelHandler;
if (item.Command == "swap" && !swapCapable)
    throw new InvalidOperationException("swap is not supported for this document type; use 'move' instead");

static bool HandlerSupportsSwap(object handler) =>
    handler is PowerPointHandler or WordHandler or ExcelHandler;

try { (p1, p2) = DispatchSwap(handler, item); }
catch (InvalidOperationException ex) when (ex.Message.Contains("swap not supported"))
{ /* fall back to 'move' or skip the item */ }

When it happens

Trigger: Running a batch that contains a 'swap' item against a document type whose handler has no Swap overload. In practice this is rare since the three main handlers are covered, but it fires for any future/custom handler.

Common situations: A pipeline that dispatches the same batch JSON across multiple file types, where one type lacks swap support. A test harness using a mock/stub handler.

Related errors

• swap not supported for this document type
• 'swap' command requires 'path' and 'path2' (or 'to') fields.
• Expected "key=value" string in props array
• Unexpected end of JSON
• Expected object or ["key=value"] array for props

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