docling-project/docling · error · RuntimeError

unexpected table dimensions: {table.data.num_rows}x{table.da

Error message

unexpected table dimensions: {table.data.num_rows}x{table.data.num_cols}

What it means

Error "unexpected table dimensions: {table.data.num_rows}x{table.data.num_cols}" thrown in docling-project/docling.

Source

Thrown at perfs/xlsx_merged_cells.py:154

) -> BenchmarkResult:
    workbook_path = output_dir / f"merged-ranges-{merge_count}.xlsx"
    generation_seconds = _create_workbook(workbook_path, merge_count=merge_count)

    tracemalloc.start()
    started = time.perf_counter()
    converter = DocumentConverter(allowed_formats=[InputFormat.XLSX])
    document = converter.convert(workbook_path).document
    conversion_seconds = time.perf_counter() - started
    _, peak_memory = tracemalloc.get_traced_memory()
    tracemalloc.stop()

    if len(document.tables) != 1:
        raise RuntimeError(
            f"expected one table for {merge_count} merges, got {len(document.tables)}"
        )
    table = document.tables[0]
    if table.data.num_rows != merge_count or table.data.num_cols != 4:
        raise RuntimeError(
            f"unexpected table dimensions: {table.data.num_rows}x{table.data.num_cols}"
        )

    return BenchmarkResult(
        python_version=runtime_info.python_version,
        platform=runtime_info.platform,
        docling_version=runtime_info.docling_version,
        commit_sha=runtime_info.commit_sha,
        merge_count=merge_count,
        non_empty_cells=merge_count * 2,
        rectangle_area=merge_count * 4,
        generation_seconds=round(generation_seconds, 6),
        conversion_seconds=round(conversion_seconds, 6),
        peak_python_memory_mb=round(peak_memory / (1024 * 1024), 3),
        table_count=len(document.tables),
    )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Confirm the workbook layout: each merged row spans columns 1-3 plus a value in column 4, so the expected table is merge_count rows by 4 columns.
2. Check how the Docling XLSX backend handles merged cells in the version under test; merged-range handling changes can alter reported num_cols.
3. Dump document.tables[0].data to inspect actual dimensions and cell placement to see whether rows or columns were collapsed.

When it happens

Trigger: Raised by perfs/xlsx_merged_cells.py when the single converted table's row/column dimensions do not match merge_count rows by 4 columns.

Common situations: Regression in XLSX table reconstruction for merged cell ranges, e.g. merged regions collapsing rows/columns or producing extra grid cells.

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/6a2263017bb4716d. Report an issue: GitHub.