QuestPDF/QuestPDF · error · ArgumentOutOfRangeException

The EnsureSpace minimum height cannot be negative.

Error message

The EnsureSpace minimum height cannot be negative.

What it means

EnsureSpace(this IContainer, float minHeight) pushes content to the next page when less than minHeight remains, to avoid tiny fragments (e.g. a lone table row at the page bottom). Negative heights are meaningless for that guarantee, so the method throws ArgumentOutOfRangeException when minHeight < 0. Zero is allowed and disables the minimum-height behavior; the default is EnsureSpace.DefaultMinHeight.

Source

Thrown at src/dotnet/library/QuestPDF/Fluent/ElementExtensions.cs:229

        /// If the required space is not available, the content is moved to the next page.
        /// </para>
        /// <para>
        /// This rule applies only to the first page where the content appears. If the content spans multiple pages,
        /// all subsequent pages are rendered without this restriction. 
        /// </para>
        /// <para>
        /// This method is particularly useful for structured elements like tables, where rendering only a small fragment 
        /// at the bottom of a page could negatively impact readability. By ensuring a minimum height, 
        /// you can prevent undesired content fragmentation.
        /// </para>
        /// <br />
        /// <a href="https://www.questpdf.com/api-reference/ensure-space.html">Learn more</a>
        /// </summary>
        /// <param name="minHeight">The minimum height, in points, that the element should occupy before a page break.</param>
        public static IContainer EnsureSpace(this IContainer element, float minHeight = Elements.EnsureSpace.DefaultMinHeight)
        {
            if (minHeight < 0)
                throw new ArgumentOutOfRangeException(nameof(minHeight), "The EnsureSpace minimum height cannot be negative.");
            
            return element.Element(new EnsureSpace
            {
                MinHeight = minHeight
            });
        }
        
        /// <summary>
        /// <para>
        /// Attempts to keep the container's content together on its first page of occurrence.
        /// If the content does not fit entirely on that page, it is moved to the next page. 
        /// If it spans multiple pages, all subsequent pages are rendered as usual without restriction.
        /// </para>
        /// <para>
        /// This method is useful for ensuring that content remains visually coherent and is not arbitrarily split.
        /// </para>
        /// <br />
        /// <a href="https://www.questpdf.com/api-reference/prevent-page-break.html">Learn more</a>

View on GitHub (pinned to 43ab125596)

Solutions

1. Clamp minHeight to 0 or a sensible positive value before calling: `Math.Max(0, requested)`.
2. Use the default argument (.EnsureSpace()) when you have no specific minimum.
3. If the value is computed from page geometry, validate the intermediate calculation rather than trusting it.

Example fix

// before
container.EnsureSpace(contentHeight - pageHeight); // can be negative

// after
container.EnsureSpace(Math.Max(0, contentHeight - pageHeight));

float safe = Math.Max(0f, minHeight);
container.EnsureSpace(safe);

static float ClampEnsureSpace(float h) => h < 0f ? 0f : h;

try { container.EnsureSpace(minHeight); }
catch (ArgumentOutOfRangeException) {
    container.EnsureSpace(0f);
}

When it happens

Trigger: Calling .EnsureSpace(minHeight) with a negative float, often from a subtracted or computed value.

Common situations: Passing page-margin math that goes negative on small pages; pulling minHeight from config without bounds checking; sign error when subtracting padding.

Related errors

• The aspect ratio must be greater than zero.
• The URL cannot be null or whitespace.
• The section name cannot be null or whitespace.
• The Grid vertical spacing cannot be negative.
• The Grid horizontal spacing cannot be negative.

AI-assisted analysis of QuestPDF/QuestPDF@43ab125596 (2026-08-13). Data as JSON: /api/errors/8cb545fbab1f0fca. Report an issue: GitHub.