Merging PDF tables that span a page break in Python
Direct answer: When a PDF table runs past the bottom of a page, almost every extractor — pdfplumber, Camelot, Docling, LlamaParse — hands you back two separate tables instead of one. The second fragment is missing the header (or repeats it, undeduplicated), and column widths can drift slightly between the two pages. The fix is a detection step that checks whether two adjacent tables share a column-count and dtype signature, with no prose between them, and a merge step that concatenates the rows while dropping the repeated header. This guide shows both in Python with pandas, and covers where the heuristic breaks down — multi-page financial statements are the case that bites hardest, because the stakes for silently losing a row are highest there.
Why this happens
A PDF has no concept of a table that continues across pages. Every extractor — regardless of whether it’s heuristic (pdfplumber, Camelot) or model-based (Docling, Marker, LlamaParse) — processes a document page by page, or at best page-aware-but-page-scoped. When a table’s rows run past where the page ends, the extractor does one of three things, and all three produce a broken result:
- Treats each page as an independent table. Page 4 yields a table with a header and 30 rows; page 5 yields a second table with no header, starting with row 31. Downstream code that expects one table gets two, and the second one looks headerless or malformed.
- Repeats the header, unmerged. Some PDF producers (and some extractors trying to be helpful) print the header row again at the top of the continuation page. If your merge logic doesn’t know to drop it, the header row ends up as a data row — a string like
"Date"sitting in a column that should hold numbers. - Drifts column boundaries slightly. Even within the same logical table, font kerning, a slightly different column width on the continuation page, or a stray annotation can shift where a coordinate-based extractor draws its column boundaries. The two fragments can end up with a different number of columns, or the same columns in a different order.
This isn’t a hypothetical edge case. It’s an open, actively-discussed problem in the tools people reach for first: Docling issue #2976 tracks continuation tables being split into two separate table objects, and llama_parse issue #290 tracks the same failure mode in LlamaParse’s output. Neither is “fixed” in the sense of a universal guarantee — it’s the kind of problem where tools get better at specific cases (repeated-header detection, consistent column counts) without claiming to solve the general one, because the general one is genuinely hard: a PDF doesn’t tell you where a table “really” ends, only where a page does.
We cover this as one item among several in the hard 20% of PDF extraction — this post is the dedicated, hands-on version: how to detect the continuation and merge it yourself.
The core signal: does fragment B continue fragment A?
Before you can merge two table fragments, you need a reliable way to decide they’re actually the same logical table and not two unrelated tables that happen to sit near a page boundary. Four signals, used together, catch almost every real case:
- Column count matches. The number of columns in the first fragment equals the number in the second. If fragment A has 6 columns and fragment B has 5, they are either not the same table or the extractor dropped a column somewhere — either way, don’t auto-merge without a closer look.
- Header similarity (or header absence). If fragment B’s first row matches fragment A’s header row (normalized for case and whitespace), that’s strong positive evidence — it’s a repeated header, the clearest signal a continuation extractor can give you. If fragment B has no header-like first row (its first row looks like data, not labels), that’s also consistent with a continuation — it’s just missing the repeat.
- Column dtype signature matches. Infer a lightweight type per column — numeric, date-like, or text — for both fragments and compare. A continuation of a financial table should have “numeric, numeric, numeric” in the same column positions on both sides. If fragment B’s column 3 looks like dates where fragment A’s column 3 looked like currency, they’re probably not the same table.
- No intervening non-table content. If fragment A ends near the bottom of page N and fragment B starts near the top of page N+1, with no paragraph, heading, or figure caption extracted between them, that’s positional evidence for continuation. A heading between the two (”## Notes to the financial statements”) is strong evidence against merging, even if the column signatures happen to match.
None of these alone is reliable — a document can have two genuinely different tables with the same column count. Combined, they’re a solid heuristic. Here’s the detector:
import re
from datetime import datetime
def infer_column_types(rows: list[list], n_cols: int) -> list[str]:
"""Classify each column as 'numeric', 'date', or 'text' from sample rows."""
types = []
for col_idx in range(n_cols):
values = [str(row[col_idx]).strip() for row in rows if col_idx < len(row)]
values = [v for v in values if v]
if not values:
types.append("empty")
continue
numeric_like = sum(1 for v in values if re.match(r"^\(?-?[\d,]+\.?\d*\)?%?$", v))
date_like = sum(1 for v in values if _looks_like_date(v))
if numeric_like / len(values) > 0.7:
types.append("numeric")
elif date_like / len(values) > 0.7:
types.append("date")
else:
types.append("text")
return types
def _looks_like_date(value: str) -> bool:
for fmt in ("%Y-%m-%d", "%m/%d/%Y", "%d-%b-%Y", "%B %d, %Y"):
try:
datetime.strptime(value, fmt)
return True
except ValueError:
continue
return False
def is_continuation(table_a: dict, table_b: dict, had_gap_content: bool = False) -> bool:
"""
Decide whether table_b (top of the next page) continues table_a
(bottom of the previous page).
"""
headers_a = [h.strip().lower() for h in table_a["headers"]]
headers_b = [h.strip().lower() for h in table_b["headers"]]
# Signal 1: column count
if len(headers_a) != len(headers_b):
return False
# Signal 4: something clearly non-table sat between the fragments
if had_gap_content:
return False
# Signal 2: repeated header, or no header-like row at all
header_repeated = headers_a == headers_b
first_row_b = [str(c).strip().lower() for c in table_b["rows"][0]] if table_b["rows"] else []
header_missing = first_row_b != headers_b # b's header doesn't look distinct from its own data
# Signal 3: dtype signature
types_a = infer_column_types(table_a["rows"], len(headers_a))
sample_b = table_b["rows"][1:] if header_repeated else table_b["rows"]
types_b = infer_column_types(sample_b, len(headers_b))
dtype_match = types_a == types_b or types_a.count("empty") or types_b.count("empty")
return (header_repeated or header_missing) and dtype_match
had_gap_content is the piece you have to wire in from whatever extractor you’re using — it’s a flag you set to True if the extractor returned any non-table block (a paragraph, heading, or caption) positioned between the bottom of fragment A’s page and the top of fragment B’s page. Most table-extraction libraries expose page-level content in a way you can check for this; if yours doesn’t, you can approximate it by checking whether fragment A’s last row sits in roughly the bottom 15% of its page and fragment B’s first row sits in roughly the top 15% of its page — a continuation candidate should be hugging both edges.
Merging the fragments
Once is_continuation() says yes, the merge itself is mechanical: concatenate rows, drop the repeated header if present, and reset the index.
import pandas as pd
def merge_table_fragments(tables: list[dict]) -> list[pd.DataFrame]:
"""
Walk a list of page-ordered table fragments (each a dict with
'headers', 'rows', and 'page') and merge consecutive continuations
into single DataFrames.
"""
merged = []
current = tables[0]
for i in range(1, len(tables)):
nxt = tables[i]
if is_continuation(current, nxt):
header = [h.strip().lower() for h in current["headers"]]
new_rows = [
row for row in nxt["rows"]
if [str(c).strip().lower() for c in row] != header
]
current = {
"headers": current["headers"],
"rows": current["rows"] + new_rows,
"page": current["page"], # keep the starting page for provenance
}
else:
merged.append(current)
current = nxt
merged.append(current)
return [pd.DataFrame(t["rows"], columns=t["headers"]) for t in merged]
Run against a list of per-page table dicts (the shape most extractors — including pdfmux — return: {"headers": [...], "rows": [[...]], "page": N}), this collapses any run of continuation fragments into one DataFrame and leaves genuinely separate tables alone:
tables = [
{"headers": ["Date", "Description", "Amount"], "rows": [["2026-01-02", "Opening balance", "1,204.55"]], "page": 4},
{"headers": ["Date", "Description", "Amount"], "rows": [["Date", "Description", "Amount"], ["2026-01-03", "Wire transfer", "-500.00"]], "page": 5},
]
dfs = merge_table_fragments(tables)
print(len(dfs)) # 1 — correctly merged, header row dropped
print(dfs[0].shape) # (2, 3)
The page field matters more than it looks — once you’ve merged, keep it on the first fragment so you can still answer “which page did this row come from” for an audit trail, which matters a lot in the documents below.
Where this bites hardest
Multi-page tables are rare in a two-page invoice and routine in a few specific document categories — which is exactly why this failure mode gets reported against financial-document-heavy tools (both the Docling and LlamaParse issues above surfaced from users processing exactly this kind of document):
| Document type | Why tables span pages | What breaks if you don’t merge |
|---|---|---|
| SEC 10-K / 10-Q filings | Balance sheets, income statements, and especially footnote schedules routinely run 2-4 pages | A “Total assets” row ends up disconnected from the line items that sum to it — see our SEC 10-K extraction guide for the broader filing structure |
| Bank / brokerage statements | A transaction ledger can be dozens to hundreds of rows for an active account | A running-balance reconciliation silently mismatches because half the transactions are in a second, headerless fragment — see bank statement extraction |
| Audited financial statements | Notes to the financial statements contain long schedules (debt maturities, lease schedules, segment data) | Auditors and analysts cross-foot totals; a dropped row from a failed merge changes a total without raising an error |
| Compliance / regulatory filings | Line-item schedules (holdings, exposures, disclosures) are often the entire point of the filing | A compliance check runs against an incomplete table and passes when it shouldn’t |
The common thread: these are documents where the table is the payload, and the consumer of the extracted data — a reconciliation script, an auditor, a regulator — is specifically going to sum or cross-check it. A table that silently loses its continuation isn’t a formatting nuisance here; it’s a wrong number that looks exactly like a right number. See extracting financial statement data from PDFs for the broader set of financial-document failure modes this sits alongside.
Validate before you trust the merge
Because the detection heuristic above is still a heuristic, add a sanity check after merging rather than assuming it worked:
def validate_merge(df: pd.DataFrame, expected_min_rows: int | None = None) -> list[str]:
warnings = []
if df.isna().all(axis=1).any():
warnings.append("fully blank row present — possible page-break artifact not cleaned up")
# A header-looking row stuck in the data usually means the dedup missed a variant
header_lower = [str(c).strip().lower() for c in df.columns]
for i, row in df.iterrows():
if [str(v).strip().lower() for v in row] == header_lower:
warnings.append(f"row {i} duplicates the header — merge dedup missed a formatting variant")
if expected_min_rows and len(df) < expected_min_rows:
warnings.append(f"only {len(df)} rows — expected at least {expected_min_rows}, check for a dropped fragment")
return warnings
If you have an independent total to check against — a “Total” row in the source table, or a balance you can recompute — cross-footing that total against the sum of the merged rows catches the specific failure mode where a continuation fragment got missed entirely rather than mis-merged. A merge that silently drops an entire page’s fragment produces a DataFrame that looks perfectly well-formed; only the total gives it away.
How pdfmux handles this
You can run the detection-and-merge logic above yourself against any extractor’s per-page output. pdfmux’s extraction pipeline is built to do this step for you: it looks for the same continuation signals — a repeated header row, a matching column structure across the page boundary — and stitches the fragments into a single table object rather than returning two.
from pdfmux import process
result = process("10-q-filing.pdf", quality="high", output_format="json")
for table in result.tables:
print(f"page {table['page']}: {len(table['rows'])} rows, {len(table['headers'])} cols")
# A merged continuation table reports its starting page and the full
# combined row count — you don't get two separate fragments to stitch.
Worth being precise about what this does and doesn’t guarantee: table continuity across a page break is a genuinely hard problem industry-wide, not a solved one, and that holds for pdfmux too — see the hard 20% of PDF extraction for the honest version of that claim. The reason to still prefer an extractor that attempts this over one that doesn’t isn’t a guarantee of perfection; it’s that result.confidence gives you a per-page signal to decide where to spot-check, instead of silently shipping two disconnected table fragments with no indication anything needs a second look. Whether you run the merge yourself or let an extractor attempt it, the validation step above is the part that shouldn’t be optional — the failure mode here is not “this fails loudly,” it’s “this returns a plausible-looking table with a number quietly missing.”
The takeaway
Two table fragments that straddle a page break are a detection problem before they’re a merge problem. Check column count, header repetition (or absence), column dtype signature, and whether anything non-table sits between them — if all four line up, concatenate the rows and drop the repeated header. Don’t trust the merge blindly: validate against a row-count expectation or a cross-footed total, because a silently incomplete merge produces a DataFrame that looks exactly as clean as a correct one. This is one specific instance of the broader pattern in PDF extraction — the failures that matter aren’t the ones that crash, they’re the ones that return something plausible and wrong. For the rest of that pattern across multi-column layouts, scanned pages, and encoding issues, see the hard 20% of PDF extraction and extracting tables from PDF in Python for the underlying method comparison.