How-to3 min read

Empty Table Export (204): Your PDF Probably Has No Columns

PDF to Excel and PDF to CSV return HTTP 204 when no table blocks are detected—intentional, not a crash. OCR scans first; prose-only PDFs stay empty.

By the PDF123 team · Updated 2026-10-02
Empty Table Export (204): Your PDF Probably Has No Columns

If PDF to Excel or PDF to CSV finishes with HTTP 204 No Content and no download body, the extractor found zero table blocks. That status is deliberate: the API refuses to invent an empty spreadsheet when the layout heuristic sees no columns.

What the extractor looks for

Both tools share the same pipeline. The server runs pdftotext -layout, splits pages on form-feed boundaries, and groups lines that look like columnar blocks. A line counts as tabular when it contains at least two consecutive spaces (layout-mode column gutters). A block is kept only when it has at least two such lines; a lone spaced line is discarded so headings do not become one-row "tables."

PDF to CSV (POST /api/v1/convert/pdf/csv) emits one CSV per detected table (named with page and table index), or a ZIP when there are several. PDF to Excel (POST /api/v1/convert/pdf/xlsx) writes one workbook with a sheet per detected table.

When that list is empty, both return Output::no_content() mapped to 204. A 200 with a blank .xlsx would be easier to misread as success; 204 means "nothing to export."

Common reasons you get 204

  • Prose-only PDF: narrative text without clear column alignment. Use PDF to Text or PDF to Markdown instead.
  • Scanned pages with no text layer: pdftotext output is empty, so no tables appear. Run OCR first with the searchable PDF output, then retry the export on that PDF only if the words actually form columns.
  • Tables drawn as lines/images only: visual grids without extractable cell text will not become sheets.
  • Messy multi-column magazine layouts: the heuristic may miss blocks that a human calls a "table," or merge reading order badly.
  • Single-row "tables": one spaced line never becomes a block; you need at least two tabular lines.

Encrypted files need an authorized Unlock before extraction. Repair a damaged file with Repair if Get Info or the export cannot open it.

What 204 is not

204 is not a transport failure, not a timeout, and not "the server forgot the attachment." Treat it as a successful decision: no table blocks. Retrying the identical file without changing the text layer or layout will return 204 again. Scripts should branch on status code, not on an empty filename.

OCR Markdown from OCR is a text extract for agents, not a spreadsheet. If you paste OCR output into a .md file and later need columns, you still need a layout that pdftotext -layout (or a human) can see as gutters—re-exporting the same scan PDF without a text layer will keep returning 204.

What to do next

  1. Open the PDF and confirm you can select cell text. If not, OCR, then decide whether the recovered text is columnar enough for this heuristic.
  2. Prefer PDF to Excel when you expect several tables (one sheet each). Prefer PDF to CSV for a single flat file or a ZIP of CSVs.
  3. If the page is narrative, switch tools; table export will keep returning 204.
  4. For agent or pipeline status handling, map 204 → "no tables detected," not a generic retry loop.
  5. If you only need the words, stop at PDF to Text or PDF to Markdown; forcing a spreadsheet shape on prose will keep returning 204.

No account is required for the browser path. Same endpoints over HTTP: Developers. Send an Idempotency-Key on retries if your client may POST twice (Idempotency-Key).

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool