iOfficeAI/OfficeCLI · error · ArgumentException

Unknown align value '{shpAlign}'. Valid: left, center, right

Error message

Unknown align value '{shpAlign}'. Valid: left, center, right, justify.

What it means

Thrown when a shape paragraph's `align=` property does not match a recognized horizontal-alignment token. The switch accepts left, center, right, justify (aliases l, c/ctr, r, just). Any other token — e.g. `align=justify-all`, `align=distributed`, `align=start` — hits the default arm and throws. This is the paragraph-level (not run-level) alignment on the TextBody paragraph.

Source

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

            // Fonts last (schema order). Accept `font=Arial` or `font.name=Arial`.
            string? rawFontName = properties.GetValueOrDefault("font.name")
                ?? properties.GetValueOrDefault("font");
            if (rawFontName != null)
            {
                rPr.AppendChild(new Drawing.LatinFont { Typeface = rawFontName });
                rPr.AppendChild(new Drawing.EastAsianFont { Typeface = rawFontName });
            }

            var pPr = new Drawing.ParagraphProperties();
            if (properties.TryGetValue("align", out var shpAlign))
            {
                pPr.Alignment = shpAlign.ToLowerInvariant() switch
                {
                    "center" or "c" or "ctr" => Drawing.TextAlignmentTypeValues.Center,
                    "right" or "r" => Drawing.TextAlignmentTypeValues.Right,
                    "left" or "l" => Drawing.TextAlignmentTypeValues.Left,
                    "justify" or "just" => Drawing.TextAlignmentTypeValues.Justified,
                    _ => throw new ArgumentException(
                        $"Unknown align value '{shpAlign}'. Valid: left, center, right, justify.")
                };
            }

            txBody.AppendChild(new Drawing.Paragraph(
                pPr,
                new Drawing.Run(rPr, new Drawing.Text(line))
            ));
        }

        var shape = new XDR.Shape(
            new XDR.NonVisualShapeProperties(
                new XDR.NonVisualDrawingProperties { Id = shpId, Name = shpName },
                new XDR.NonVisualShapeDrawingProperties()
            ),
            spPr,
            txBody
        );

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use left, center, right, or justify (aliases l, c/ctr, r, just).
2. Omit `align=` to inherit the paragraph default.

Example fix

// before
add ./book.xlsx /Sheet1 shape --type textbox --prop font.text=Hi --prop align=start
// after
add ./book.xlsx /Sheet1 shape --type textbox --prop font.text=Hi --prop align=left

var validAlign = new[]{"left","l","center","c","ctr","right","r","justify","just"};
if (!validAlign.Contains((align ?? "").ToLowerInvariant()))
    throw new InvalidOperationException($"Invalid align '{align}'");

static readonly HashSet<string> AlignTokens = new(StringComparer.OrdinalIgnoreCase)
    {"left","l","center","c","ctr","right","r","justify","just"};
static bool IsValidAlign(string? v) => v is not null && AlignTokens.Contains(v);

try { handler.Add(...); }
catch (ArgumentException ex) when (ex.Message.Contains("Unknown align"))
{ /* reprompt with the four canonical values */ }

When it happens

Trigger: Passing `--prop align=distributed` or `--prop align=start` (CSS/HTML vocabulary) or `align=center-justify`. The switch is case-insensitive via ToLowerInvariant but does not accept XML enum spellings like `center` vs `ctr` beyond the listed aliases.

Common situations: Mapping from CSS (`text-align: justify`) but using a non-listed variant like `justify-all`; using OOXML enum string `distributed` which isn't exposed on this Add path.

Related errors

• Invalid valign value: '{shpValign}'. Valid: top, center, bot
• Unknown underline value '{shpUnder}'. Valid: single, double,
• Invalid sparkline type: '{spkTypeStr}'. Valid values: line,
• Unknown displayEmptyCellsAs value '{deca}'. Valid: gap, span
• Invalid '{propertyName}' value '{value}'. Expected a non-neg

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