QuestPDF/QuestPDF · error · DocumentComposeException

{prefix} A cell must span at least one column. Got {cell.Col

Error message

{prefix} A cell must span at least one column. Got {cell.ColumnSpan}.

What it means

ValidateCellPositions throws DocumentComposeException when a cell's ColumnSpan < 1 - a cell must cover at least one column. The offending ColumnSpan value is reported in the message with the standard configuration-issue prefix.

Source

Thrown at src/dotnet/library/QuestPDF/Elements/Table/TableLayoutValidator.cs:26

        public static void ValidateCellPositions(this Table table)
        {
            ValidateCellPositions(table.Columns.Count, table.Cells);
        }
        
        private static void ValidateCellPositions(int columnsCount, ICollection<TableCell> cells)
        {
            const string prefix = "Detected issue in table cells configuration.";
            
            foreach (var cell in cells)
            {
                if (cell.Column < 1)
                    throw new DocumentComposeException($"{prefix} A cell column position should be greater or equal to 1. Got {cell.Column}.");
                
                if (cell.Row < 1)
                    throw new DocumentComposeException($"{prefix} A cell row position should be greater or equal to 1. Got {cell.Row}.");
                
                if (cell.ColumnSpan < 1)
                    throw new DocumentComposeException($"{prefix} A cell must span at least one column. Got {cell.ColumnSpan}.");
                
                if (cell.RowSpan < 1)
                    throw new DocumentComposeException($"{prefix} A cell must span at least one row. Got {cell.RowSpan}.");
                
                if (cell.Column > columnsCount)
                    throw new DocumentComposeException($"{prefix} Cell starts at column that does not exist. Cell details: {GetCellDetails(cell)}.");
                
                if (cell.Column + cell.ColumnSpan - 1 > columnsCount)
                    throw new DocumentComposeException($"{prefix} Table cell location is incorrect. Cell spans over columns that do not exist. Cell details: {GetCellDetails(cell)}.");
            }

            string GetCellDetails(TableCell cell)
            {
                return $"Row {cell.Row}, Column {cell.Column}, RowSpan {cell.RowSpan}, ColumnSpan {cell.ColumnSpan}";
            }
        }
    }
}

View on GitHub (pinned to 43ab125596)

Solutions

1. Ensure ColumnSpan is at least 1 for every cell.
2. When computing span from start/end indices, use (end - start + 1).
3. Validate the computed span is >= 1 before configuring the cell.

Example fix

// before:
cell.Column(start).ColumnSpan(end - start); // 0 when start==end

// after:
cell.Column(start).ColumnSpan(end - start + 1);

if (cell.ColumnSpan < 1) throw new ArgumentException("ColumnSpan must be >= 1", nameof(cell.ColumnSpan));

static bool IsValidColumnSpan(int span) => span >= 1;

When it happens

Trigger: Configuring a cell with .ColumnSpan(0), a negative span, or a computed span that resolves to <= 0.

Common situations: Computing ColumnSpan as (endCol - startCol) without adding 1; default(int) used as span; off-by-one in span math.

Related errors

• {prefix} A cell column position should be greater or equal t
• {prefix} A cell row position should be greater or equal to 1
• {prefix} A cell must span at least one row. Got {cell.RowSpa
• {prefix} Cell starts at column that does not exist. Cell det
• {prefix} Table cell location is incorrect. Cell spans over c

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