spectreconsole/spectre.console · error · ArgumentException

Column span must be at least 1.

Error message

Column span must be at least 1.

What it means

TableCell.Span(int span) sets how many columns a body cell covers. The constructor defaults ColumnSpan to 1, and Span() rejects any value below 1 because a cell must occupy at least one column. Passing 0 or a negative number throws ArgumentException on the 'span' parameter.

Source

Thrown at src/Spectre.Console/Widgets/Table/TableCell.cs:46

    /// <summary>
    /// Initializes a new instance of the <see cref="TableCell"/> class.
    /// </summary>
    /// <param name="markup">Markup text.</param>
    public TableCell(string markup)
        : this(new Markup(markup ?? string.Empty))
    {
    }

    /// <summary>
    /// Sets the number of columns this cell should span.
    /// </summary>
    /// <param name="span">The number of columns to span.</param>
    /// <returns>The same instance so that multiple calls can be chained.</returns>
    public TableCell Span(int span)
    {
        if (span < 1)
        {
            throw new ArgumentException("Column span must be at least 1.", nameof(span));
        }

        ColumnSpan = span;
        return this;
    }

    /// <summary>
    /// Implicitly converts a <see cref="string"/> to a <see cref="TableCell"/>.
    /// </summary>
    /// <param name="markup">The markup text to convert.</param>
    public static implicit operator TableCell(string markup)
    {
        return new TableCell(markup);
    }

    /// <inheritdoc/>
    Measurement IRenderable.Measure(RenderOptions options, int maxWidth)
    {

View on GitHub (pinned to 0acc92fada)

Solutions

1. Clamp the value before calling Span: cell.Span(Math.Max(1, computedSpan)).
2. If the cell should cover exactly one column, omit the Span() call entirely (default ColumnSpan is 1).
3. Guard the computed span and skip/merge the cell when it would be 0, rather than calling Span with it.
4. Validate external/config values at the boundary: if (value < 1) throw or default to 1.

Example fix

// before
var cell = new TableCell(text).Span(columns - currentIndex); // 0 on last column

// after
var span = Math.Max(1, columns - currentIndex);
var cell = new TableCell(text).Span(span);

if (span < 1) span = 1; // or throw at your boundary
cell.Span(span);

When it happens

Trigger: Calling cell.Span(0), cell.Span(-1), or any value < 1. Most common when span is computed (loop counters, column-remainder math, data-driven widths) and the computation can legally produce zero (e.g. last column, empty data range, Math.Max(0, ...)).

Common situations: Off-by-one when distributing a cell across remaining columns (e.g. columns - i evaluates to 0 on the final column); using Math.Max(0, x) instead of Math.Max(1, x); feeding a user/config value that can be 0; passing an int from a parsed config file with no lower-bound validation.

Related errors

• Column spanning is not supported in table header rows.
• Column spanning is not supported in table footer rows.
• Column spanning is not supported in table {rowType} rows.
• The number of row columns (including spans) are greater than
• Must be > 1

AI-assisted analysis of spectreconsole/spectre.console@0acc92fada (2026-08-13). Data as JSON: /api/errors/76722090afcb8caa. Report an issue: GitHub.