Repository navigation
Description
In 0.2.4 a PDF whose pages are mostly text but which contains one image-only page converts to
nothing at all: the NeedsOcr error replaces the output instead of annotating it. The pages that
have a text layer are lost with it.
Measured on 0.2.4 (Node, macOS arm64), same two text pages in both files:
| input | pages | result |
|---|---|---|
text.pdf |
2 text pages | returns 77 chars of markdown |
mixed.pdf |
the same 2 text pages + 1 image-only page | throws needsOcr, pages: [3], pageCount: 3 — no markdown |
CLI: anydoc mixed.pdf exits 3 with anydoc: page 3 of 3 needs OCR and writes nothing to stdout.
Adding a page that cannot be read removes the pages that can.
Why I think the previous behaviour was fixed in the wrong direction
The defect in ≤0.2.3 was not that the image-only page was missing from the markdown. Markdown of a
page made of pixels is genuinely not available without OCR, and anydoc is right not to do OCR. The
defect was that nothing said so: the output looked like a complete document, and a reader had
no way to know a page was absent. I measured that on 0.2.3 — a 3-page mixed PDF converts, exit 0,
no warning, page 3 simply not there.
An undeclared loss is cured by a declaration. 0.2.4 cures it by refusing, which trades a partial
result for none. For a 400-page scanned-in-parts report, one photographed page now costs the other
399.
Proposal
- Keep the hard error only where there is nothing to return — every page image-only. There the
refusal is the honest answer and 0.2.4 already gets it right. - For a mixed document, convert and report. Return the markdown, and carry
needsOcrwith
pagesandpageCounton the result rather than on an error. CLI: exit 0, the notice on
stderr, the markdown on stdout. The caller decides whether a partial document is usable —
for many pipelines it is, and today they cannot even see it. - Put a marker in the markdown where the page was. Something like
> [page 3 of 3: image-only, not converted]. This matters more than it looks: the markdown
outlives the call that produced it. Once it is written to a file or pasted into a prompt, any
result-level metadata is gone and the document looks complete again. A marker in the text is the
only signal that travels with the text.
Point 3 is the part I would argue for hardest. It is also the cheapest: one line in the renderer,
and it makes the omission legible to a human reading the output rather than only to the code that
called the API.
A note on ocr: 'hosted'
Hosted OCR is a good option to have, but it cannot be the general answer to this, because for some
callers sending the file anywhere is not a technical choice. Documents covered by a
confidentiality obligation, or belonging to a third party, stay on the machine that converts them.
Those callers need the partial conversion plus the declaration, which is exactly what proposal 2
and 3 give them.
Reproduction
// npm i @firecrawl/anydoc pdfkit
const PDFDocument = require('pdfkit');
const { createWriteStream, writeFileSync } = require('node:fs');
const { toMarkdown } = require('@firecrawl/anydoc');
// an 8x8 grey PNG, enough to make a page that holds no text
writeFileSync('px.png', Buffer.from(
'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAAAAADhZOFXAAAAAmJLR0QA/4ePzL8AAAAHdElNRQfqCBsUHRbc9Nv6AAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDI2LTA4LTI3VDIwOjI5OjIyKzAwOjAwzqQJtwAAACV0RVh0ZGF0ZTptb2RpZnkAMjAyNi0wOC0yN1QyMDoyOToyMiswMDowML/5sQsAAAAodEVYdGRhdGU6dGltZXN0YW1wADIwMjYtMDgtMjdUMjA6Mjk6MjIrMDA6MDDo7JDUAAAAEElEQVQI12OsZ4AAJgaKGAAlwQCP/uWZYwAAAABJRU5ErkJggg==', 'base64'));
function build(file, withImage) {
const doc = new PDFDocument({ autoFirstPage: false });
const out = createWriteStream(file);
const done = new Promise((r) => out.on('finish', r));
doc.pipe(out);
doc.addPage().font('Helvetica').fontSize(14).text('Page one: native text, readable without OCR.');
doc.addPage().font('Helvetica').fontSize(14).text('Page two: more native text.');
if (withImage) doc.addPage().image('px.png', 0, 0, { width: 612 });
doc.end();
return done;
}
(async () => {
await build('text.pdf', false);
await build('mixed.pdf', true);
for (const f of ['text.pdf', 'mixed.pdf']) {
try { console.log(f, '→', (await toMarkdown(f)).length, 'chars'); }
catch (e) { console.log(f, '→ throws', e.code, JSON.stringify(e.pages), e.pageCount); }
}
})();text.pdf → 77 chars
mixed.pdf → throws needsOcr [3] 3
Activity
phenomen commentedon Aug 27, 2026
I have the same issue w/ wasm build.
needsOcrthrows an error and aborts the entire process instead of just logging which pages need OCR.corocojam commentedon Aug 28, 2026
Confirmed on the Python binding as well (firecrawl-anydoc 0.2.4, Python 3.12.10, macOS arm64): a 2-page PDF — page 1 native text, page 2 image-only — raises
NeedsOcrErrorwithpages=[2],page_count=2fromto_markdown, and the default local conversion returns no partial markdown for the text page.One data point for proposal 2: running pdf-inspector 1.17.0 (PyPI) directly on the same file already exposes most of the information that proposal would need:
classify_pdf→mixed, confidence 0.65, page count correctextract_pages_markdown→ page 0 (0-based) returns its full markdown withneeds_ocr=False; page 1 returns empty withneeds_ocr=True,ocr_reason="scanned"; the result carriespages_needing_ocr=[2](1-based)So one layer down, the extractor returns partial markdown plus a per-page needs-OCR report. anydoc 0.2.4 bundles the pdf-inspector crate at 1.14.2 (per its SBOM), and I have not checked whether that version already exposes equivalent per-page results — but proposal 2 might be implementable mostly by surfacing per-page results the extractor already computes. +1 to the in-text marker of proposal 3 as well.
larue-greenboard commentedon Aug 31, 2026
Agree we are having the same issue
larue-greenboard commentedon Aug 31, 2026
Opened #153 for this.
It adds an opt-in
skipmode —--ocr skip,{ ocr: 'skip' },ocr="skip",Ocr::Skip— that converts the pages carrying text and reports the ones it left out. On an 80-page document with one image-only page at page 3, the default returns 0 bytes and exits 3;--ocr skipreturns 79 pages and exits 0. The default path is unchanged byte for byte, so #140's behaviour is still what you get unless you ask for something else.Against the three suggestions:
NeedsOcr, which keeps--ocr hostedand exit code 3 working as the "this needs real OCR" signal.needsOcras metadata on success — done.skipresolves toConversion { markdown, pages_needing_ocr, page_count }.@corocojam your reading was right: pdf-inspector already returns the per-page results, so no version bump was needed (1.14.2 has
extract_pages_markdown_memwith per-pageneeds_ocr). One thing that surprised me while implementing it — the whole-document path isn't just lossy on these files, it's all-or-nothing:process_pdf_memclassifies a mixed document asImageBasedand returnsmarkdown: Nonefor the entire document, even where individual pages carry clean text. So this isn't a matter of tolerating a partial result; the readable pages have to come from the per-page call.@phenomen wasm is covered too, via
toMarkdownBytesWith(bytes, format, 'skip').