iOfficeAI/OfficeCLI · error · ArgumentException

'anchor-xml' property is required for drawing-group (verbati

Error message

'anchor-xml' property is required for drawing-group (verbatim xdr anchor XML)

What it means

The drawing-group carrier requires the full <xdr:twoCellAnchor> markup that hosts the group, supplied as the 'anchor-xml' property. Because grouped shapes have no semantic add vocabulary, the entire anchor (with its child coordinate system, z-order, and styles) is carried verbatim. A null/missing 'anchor-xml' key leaves the handler with nothing to append.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.cs:1125

                var chartIdx = drawingsPart.ChartParts.ToList().IndexOf(chartPart);
                return (relId, $"/{sheetName}/chart[{chartIdx + 1}]");

            case "drawing-group":
            {
                // Verbatim DrawingML group carrier for xlsx dump→batch.
                // The full hosting anchor is preserved because flattening a
                // <xdr:grpSp> loses the child coordinate system, z-order,
                // styles and the fact that the objects are grouped. Only
                // hyperlink relationships are carried here; dump falls back
                // to semantic leaf shapes when a group references package
                // parts such as images/charts.
                var groupSheetName = parentPartPath.TrimStart('/');
                var groupWorksheet = FindWorksheet(groupSheetName)
                    ?? throw new ArgumentException(
                        $"Sheet not found: {groupSheetName}. drawing-group must be added under a sheet.");
                properties ??= new Dictionary<string, string>();
                var anchorXml = properties.GetValueOrDefault("anchor-xml")
                    ?? throw new ArgumentException(
                        "'anchor-xml' property is required for drawing-group (verbatim xdr anchor XML)");

                XDR.TwoCellAnchor groupAnchor;
                try
                {
                    groupAnchor = new XDR.TwoCellAnchor(anchorXml);
                }
                catch (Exception ex)
                {
                    throw new ArgumentException(
                        $"drawing-group anchor XML is not a valid xdr:twoCellAnchor: {ex.Message}", ex);
                }
                if (groupAnchor.GetFirstChild<XDR.GroupShape>() == null)
                    throw new ArgumentException(
                        "drawing-group anchor XML must contain a top-level xdr:grpSp.");

                List<DumpDrawingHyperlinkSpec> groupHyperlinks;
                try

View on GitHub (pinned to 1ced45e900)

Solutions

Add properties["anchor-xml"] with the complete <xdr:twoCellAnchor>...</xdr:twoCellAnchor> markup.
Re-dump the source workbook so the anchor-xml is regenerated from the real group.
If authoring by hand, copy the anchor XML from the source xlsx's xl/drawings/drawingN.xml.

Example fix

// before
var props = new Dictionary<string,string> { ["hyperlinks"] = "" };
handler.AddPart("/Sheet1", "drawing-group", props);
// after
props["anchor-xml"] = "<xdr:twoCellAnchor xmlns:xdr=\"...\">...<xdr:grpSp>...</xdr:grpSp></xdr:twoCellAnchor>";
handler.AddPart("/Sheet1", "drawing-group", props);

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(properties?.GetValueOrDefault("anchor-xml")))
    throw new InvalidOperationException("anchor-xml missing — supply the verbatim twoCellAnchor XML.");

Type guard

static bool HasAnchorXml(Dictionary<string,string>? p) =>
    !string.IsNullOrEmpty(p?.GetValueOrDefault("anchor-xml"));

Try / catch

try { handler.AddPart(parent, "drawing-group", props); }
catch (ArgumentException ex) when (ex.Message.Contains("'anchor-xml' property is required"))
{ /* populate props["anchor-xml"] then retry */ }

Prevention

Treat anchor-xml as mandatory in any batch authoring helper.
Re-dump to regenerate the anchor XML rather than hand-writing it.
Unit-test batch builders to reject missing anchor-xml before submission.

When it happens

Trigger: AddPart(...) called with a properties dictionary that has no 'anchor-xml' key, or whose value is null/empty. Typical of a hand-written batch or a dump→batch serialization that dropped the field.

Common situations: Manually authoring an add-part batch and omitting anchor-xml; a JSON/cell transport layer that stripped the long XML string; re-using a picture/shape property bag that never had anchor-xml.

Related errors

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