First, a reassuring fact: anydoc's error semantics are clean — every language shares one ConvertError, mapped consistently, with consistent debugging paths. This page walks through all six errors and the known limits.

Six errors, one table

Error	Meaning	Common trigger	What to check
unsupported	Unsupported format	Scanned PDF, obscure proprietary format	Verify the real format; scanned PDFs need OCR
malformed	Corrupt or unusable	Truncated file, renamed text file	Re-save with the original application
encrypted	Document is encrypted	Password-protected docx/xlsx/pdf	Remove the password first
resourceLimit	Crossed a safety limit	Huge file, zip bomb	Split the file; confirm the source is trusted
missingPart	Required part absent	Incomplete OOXML file	Re-export / re-download the full file
io	Underlying I/O error (native only)	Missing path, no permission, file lock	Check path, permissions, process locks

How each language surfaces it

// Node.js
catch (e) { e.code }            // 'unsupported', etc.

# Python
except anydoc.UnsupportedError:  # exception subclass

// Rust
match err {
    anydoc::ConvertError::Unsupported => ...
}

Known limits (the important part)

Scanned PDFs are not supported

Image-only / scanned PDFs need OCR, and anydoc returns unsupported. This is a deliberate boundary, not a bug — anydoc only handles text-based PDFs locally (via pdf-inspector).

Workarounds:

• Need OCR? Use Firecrawl Parse — it layers OCR onto the same conversion pipeline
• Or OCR locally first (tesseract and friends), then feed the resulting text to anydoc

Headers, footers, page numbers are stripped

All formats uniformly exclude headers, footers, page numbers, and date/time placeholders — intentional, for clean LLM input. There is currently no toggle.

Visual detail is not preserved

Output is Markdown, not a PDF snapshot. Complex layouts (absolutely positioned text boxes, WordArt, intricate charts) degrade to readable text. Completeness is assured by the benchmark's 87, but pixel-perfect reproduction is out of scope.

Very large files have a ceiling

Decompression, nesting depth, and node count are capped by fixed safety limits. Monster files (hundreds of MB) may hit resourceLimit — split them first.

Frequent questions

The output is empty or nearly empty?

First verify the file isn't a scan; then open it in the original application to confirm it's not corrupt; finally, check whether it's encrypted.

Why don't my merged table cells survive?

Merged cells become a regularized Markdown table (the "tables" dimension scored 78 in the benchmark), but Markdown itself can't express merges — the content is all there, the visual merge is lost.

Why did my images become text?

Images render as alt text by default; the raw bytes stay on the document model (toDocument). To extract them, read the asset nodes and write each file.

Conversion is slow?

A normal document converts in under 5ms median. If it's slow, the file is probably huge or anomalous — or you're re-initializing the WASM in a loop (call init() once).

How do I verify nothing went wrong?

Spot-check three things: heading levels (# counts), table structure, and lists/code blocks. For batch conversions, snapshot-test the critical documents.

One-liner

Six errors, three boundaries (scanned PDFs, header/footer stripping, no visual fidelity) — remember these and most anydoc pitfalls never reach you.

Contributors: souvc