iOfficeAI/OfficeCLI · error · ArgumentException

drawing-group 'hyperlinks' carrier is invalid: {ex.Message}

Error message

drawing-group 'hyperlinks' carrier is invalid: {ex.Message}

What it means

DecodeDumpDrawingHyperlinks threw a FormatException while parsing the compact 'hyperlinks' property. The carrier format is `base64(id),base64(target),0|1` entries joined by '|'. It throws when an entry does not split into exactly three comma-separated fields, the third field is not '0'/'1', or a base64 segment fails to decode. The original FormatException message is embedded.

Source

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

                }
                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
                {
                    groupHyperlinks = DecodeDumpDrawingHyperlinks(
                        properties.GetValueOrDefault("hyperlinks") ?? "");
                }
                catch (FormatException ex)
                {
                    throw new ArgumentException(
                        $"drawing-group 'hyperlinks' carrier is invalid: {ex.Message}", ex);
                }

                Modified = true;
                var groupDrawingsPart = groupWorksheet.DrawingsPart
                    ?? groupWorksheet.AddNewPart<DrawingsPart>();
                if (groupDrawingsPart.WorksheetDrawing == null)
                {
                    groupDrawingsPart.WorksheetDrawing = new XDR.WorksheetDrawing();
                    groupDrawingsPart.WorksheetDrawing.Save();
                }
                var groupSheet = GetSheet(groupWorksheet);
                if (groupSheet.GetFirstChild<SpreadsheetDrawing>() == null)
                {
                    var drawingRelId = groupWorksheet.GetIdOfPart(groupDrawingsPart);
                    groupSheet.Append(new SpreadsheetDrawing { Id = drawingRelId });
                    SaveWorksheet(groupWorksheet);
                }

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Build the carrier with EncodeDumpDrawingHyperlinks rather than by hand, so field count and base64 are guaranteed.
  2. If editing manually, keep to exactly base64(id),base64(target),0|1 joined by '|' with no empty entries.
  3. Omit the 'hyperlinks' key entirely when there are no hyperlinks (empty string is accepted and yields no entries).
  4. Round-trip a known-good carrier through Decode in a test to spot the offending entry.

Example fix

// before — hand-rolled, wrong delimiter / field count
props["hyperlinks"] = "rId1;https://x.com;1";
// after — use the encoder
props["hyperlinks"] = EncodeDumpDrawingHyperlinks(new[]{
    new DumpDrawingHyperlinkSpec { Id="rId1", Target="https://x.com", IsExternal=true }});
Defensive patterns

Strategy: try-catch

Validate before calling

try { DecodeDumpDrawingHyperlinks(props.GetValueOrDefault("hyperlinks") ?? ""); }
catch (FormatException ex) { /* carrier malformed — rebuild with Encode */ }

Type guard

static bool HyperlinksCarrierOk(string encoded)
{ try { DecodeDumpDrawingHyperlinks(encoded); return true; } catch { return false; } }

Try / catch

try { handler.AddPart(parent, "drawing-group", props); }
catch (ArgumentException ex) when (ex.Message.Contains("'hyperlinks' carrier is invalid"))
{ /* rebuild with EncodeDumpDrawingHyperlinks, then retry */ }

Prevention

When it happens

Trigger: The hyperlinks string is hand-edited, contains extra commas inside a base64 segment (base64 itself never does, so this implies tampering), uses a different delimiter, has a stray '|', or one segment's base64 is corrupted.

Common situations: Manually constructing the carrier instead of using EncodeDumpDrawingHyperlinks; a search/replace that altered delimiters; truncation mid-entry; an empty entry that still has a stray comma.

Related errors

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