iOfficeAI/OfficeCLI · error · ArgumentException

{keyName} must be in range {PageDimMinTwips}–{PageDimMaxTwip

Error message

{keyName} must be in range {PageDimMinTwips}–{PageDimMaxTwips} twips (~0.4cm–55.9cm), got {twips}.

What it means

Thrown by WordPageDefaults.ValidatePageDim when a page width/height (w:pgSz/@w:w or @w:h) is outside the OOXML-legal range 240..31680 twips (~0.4cm..55.9cm). The lower bound 240 (1/6 inch) is the smallest that produces a renderable page in Word; the upper bound 31680 (22 inch) is the EcmaSpec max. Values outside this range are rejected rather than clamped.

Source

Thrown at src/officecli/Core/WordPageDefaults.cs:27

/// must always read the source <c>SectionProperties</c> first and only
/// drop to these defaults when the value is genuinely absent.
/// </summary>
public static class WordPageDefaults
{
    // A4: 210mm × 297mm at 1440 twips/inch (= 567 twips/cm).
    public const uint A4WidthTwips = 11906;
    public const uint A4HeightTwips = 16838;

    // OOXML legal range for w:pgSz/@w:w and @w:h. Word's UI clamps roughly to
    // ~0.4cm–55.9cm; the EcmaSpec defines 1..31680 (22"). Use 240 (1/6") as the
    // lower bound — anything smaller will not produce a renderable page in Word.
    public const uint PageDimMinTwips = 240;
    public const uint PageDimMaxTwips = 31680;

    public static void ValidatePageDim(long twips, string keyName)
    {
        if (twips < PageDimMinTwips || twips > PageDimMaxTwips)
            throw new ArgumentException(
                $"{keyName} must be in range {PageDimMinTwips}–{PageDimMaxTwips} twips " +
                $"(~0.4cm–55.9cm), got {twips}.");
    }
}

View on GitHub (pinned to 1ced45e900)

Solutions

1. Provide a page dimension in 240..31680 twips (e.g. A4 = 11906 x 16838 twips).
2. Double-check units: 1 inch = 1440 twips, 1 cm = 567 twips, 1 pt = 20 twips.
3. If the value came from another unit, convert correctly before passing twips.

Example fix

// before: passed points as if twips -> far below 240
WordPageDefaults.ValidatePageDim(21, "pageWidth");  // 21 twips ~ 0.015 inch
// after: convert cm -> twips (1cm = 567 twips)
WordPageDefaults.ValidatePageDim((long)Math.Round(21.0 * 567), "pageWidth"); // A4 width

static bool IsValidPageDim(long twips)
    => twips >= WordPageDefaults.PageDimMinTwips && twips <= WordPageDefaults.PageDimMaxTwips;

try { WordPageDefaults.ValidatePageDim(twips, keyName); }
catch (System.ArgumentException ex) when (ex.Message.Contains("twips"))
{ /* clamp into range or report the accepted range to the user */ }

When it happens

Trigger: Setting page width/height (pageWidth/pageHeight or section pgSz) to a value below 240 twips or above 31680 twips; e.g. a near-zero size, or a very large custom page; replaying a doc with a corrupt pgSz.

Common situations: Unit confusion (passing points/cm where twips expected, or vice-versa); a corrupt source document with a garbage pgSz; an automation layer computing geometry incorrectly.

Related errors

• Invalid 'softedge' value '{value}'. Expected a finite non-ne
• Invalid {paramName} value: '{raw}'.
• Invalid spacing value '{value}'. Spacing must be non-negativ
• Invalid 'lineSpacing' value '{raw}'. Line spacing must be gr
• Invalid 'lineSpacing' value '{raw}'. Line spacing must not b

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