Error Handling

The same failure modes apply across all three SDKs — only how they surface differs:

from py_chunks import get_chunks

try:
    chunks = get_chunks("report.xyz")
except FileNotFoundError as e:
    ...   # File not found: report.xyz
except ValueError as e:
    ...   # unsupported extension, bad mode, bad window/overlap
except RuntimeError as e:
    ...   # the document could not be parsed

# Real messages:
# ValueError: Unsupported file type '.xyz'. Supported: .csv, .doc, .docm, ...
# ValueError: mode must be one of ['default', 'page_aware', 'section',
#             'semantic', 'sentence', 'sliding_window', 'structural'] for MD,
#             got: 'nope'
# ValueError: overlap must be less than window_size
# ValueError: filename is required when source is bytes

The variant table

The engine has four error variants. Each SDK expresses them in its own idiom; this is the mapping, read from the bindings:

Message parity — and where it stops

Parse messages produced by the engine are byte-identical across the SDKs. A corrupt DOCX raises exactly the same sentence everywhere — verified live, on both the path and the bytes route:

DOCX is not a valid zip archive: invalid Zip archive: Could not find EOCD

Two further gaps sit in messages Python builds in its own validation layer, before the engine is reached.

1. The unsupported-extension message. Python appends the full supported set, JavaScript does not:

py:  ValueError: Unsupported file type '.zip'. Supported: .csv, .doc, .docm, … .xltx
js:  ChunkError: Unsupported file type '.zip'          (kind "unsupported")

2. The invalid-mode message. Python rejects an unknown mode in its own dispatch layer using one uniform template with a sorted list; JavaScript passes the mode through and surfaces whatever the engine's per-format check says. The wording therefore differs per format, not just in ordering and quoting:

md    py: mode must be one of ['default', 'page_aware', 'section', 'semantic', 'sentence', 'sliding_window', 'structural'] for MD, got: 'nope'
      js: mode must be one of ["default", "structural", "section", "semantic", "sentence", "page_aware", "sliding_window"] for MD, got: 'nope'

txt   py: mode must be one of ['default', 'page_aware', … 'structural'] for TXT, got: 'nope'
      js: Unknown TXT mode: nope

csv   py: mode must be one of ['default', 'page_aware', 'row', 'sliding_window'] for CSV, got: 'nope'
      js: mode must be 'row', 'default', 'sliding_window', or 'page_aware' for CSV

Both SDKs agree on the classification — ValueError in Python, kind: "invalid-arg" in JavaScript — for every format. Only the sentence differs. Do not pattern-match an invalid-mode message across SDKs.

py: ValueError: overlap must be less than window_size
js: ChunkError: overlap must be less than window_size     (kind "invalid-arg")

JavaScript: ChunkError covers the whole surface

import { getChunks, ChunkError, type ChunkErrorKind } from "js-chunks";

try {
  await getChunks(bytes, { filename: "data.xyz" });
} catch (e) {
  if (e instanceof ChunkError) {
    e.kind;    // "unsupported" | "invalid-arg" | "parse" | "io" | "unknown"
    e.message; // the engine's message, byte-identical to py-chunks
  } else {
    throw e;   // see below
  }
}

Every engine failure is a ChunkError, and so is every host-side throw the wrapper performs before the engine is reached:

The contract is complete: there is no input for which getChunks / getMarkdown / streamChunks throws something that is not a ChunkError. getChunks(bytes, null) is treated as getChunks(bytes) — null is how an untyped caller spells "no options" — so it fails on the missing filename, with kind: "invalid-arg", rather than on a dereference.

ChunkError: ENOENT: no such file or directory, open './missing.md'
  e instanceof ChunkError → true
  e.kind                  → "io"

Python exception reference

Every exception py-chunks raises in its own Python layer, before the engine is reached. Read from py_chunks/_sources.py and py_chunks/_dispatch.py.

Every stream_chunks_from_* helper raises the same set as its get_chunks_from_* counterpart, and every format-specific stream_chunk_<fmt>() helper now runs the same mode and range validation as its batch counterpart. A mis-typed mode or a zero count raises ValueError from the streaming helpers too, on the first call rather than on the first next() — stream_chunk_doc and stream_chunk_ppt used to silently stream default-mode chunks for an unknown mode, and stream_chunk_docx used to raise NotImplementedError: Streaming for <mode> mode coming soon. Neither happens any more.

Unsupported or mismatched extension

Dispatch is by file extension. If the extension isn't supported — or the filename you pass with bytes doesn't match the actual content — you get an error naming the unsupported type.

Invalid mode parameters

• sliding_window: window_size must be > 0 and overlap must be strictly less than window_size — it is not clamped.
• sentence: sentences_per_chunk must be > 0.
• page_aware: paragraphs_per_page must be > 0.
• Passing a mode a format doesn't support raises, and the message names the modes that format does accept.

All of these are ValueError in Python and kind: "invalid-arg" in JavaScript, for every format — EPUB included — and on both the path and the bytes route. The range sentences are uniform too: the document formats and the spreadsheet family now use the same wording, and so do all three SDKs.

overlap must be less than window_size
window_size must be greater than 0
sentences_per_chunk must be greater than 0
paragraphs_per_page must be greater than 0
rows_per_chunk must be greater than 0     # CSV / TSV, which is what
                                          # paragraphs_per_page maps onto there

The invalid-mode sentence is the one that still varies — the two samples below are the JavaScript/engine form, and Python words it differently (see the message-parity section above). Treat them as illustrative, not a contract: branch on kind / the exception type.

mode must be one of [page_aware, row, semantic, sheet, sliding_window, table] for XLSX, got: 'nope'
mode must be 'row', 'default', 'sliding_window', or 'page_aware' for CSV

Async uploads

If you pass an upload object whose read() is a coroutine, py-chunks raises a TypeError:

upload_file.read() is async; pass upload_file.file or use bytes API

In async handlers, read the bytes yourself and use the bytes API:

data = await file.read()
chunks = get_chunks_from_bytes(data, file.filename)

Angle brackets: autolinks are kept, raw HTML is not

For the formats that render through the shared Markdown pipeline — .md, .eml, .mbox, .msg, .odt, .odp, .rtf, .json/.jsonl/.ndjson, .ipynb, .pdf and .epub — get_chunks follows CommonMark on angle brackets. DOCX, TXT, HTML and the spreadsheet family use separate chunkers and never had this behaviour.

The remaining case is deliberate and correct for real Markdown: <…> is raw inline HTML by specification, so a text-only chunk is right to strip it. Plan for it if you write about <T>, <placeholder> or <your-api-key> — escape them (\<T\>), fence them as code (`<T>`), or read the text from get_markdown, which returns everything verbatim.

Corrupt or unreadable files

Malformed documents surface parsing errors from the underlying engine. Treat failures per-document so one bad file doesn't halt a batch — see the batch recipe.

Scanned / image-only PDFs

A PDF with no text layer (a scan, or pages rendered as images) can't be chunked as text — the text modes raise:

RuntimeError: PDF contains no extractable text (100 page(s) scanned or
image-only). OCR is not enabled; pass list_images to get one rendered image
per page.

The image path is the exception: list_images=True succeeds and returns one image per page instead of raising.

A scanned page is usually a single embedded image, and that image is returned as it is stored — named image_p1_1.png, image_p2_1.png, … after the page it sits on. Only a page with no embedded image is rasterised, and those renders are named page_1.png, page_2.png, … Rendering is native-only: in the browser there is no rasteriser, so such a PDF reports that it has no text.

try:
    chunks = get_chunks("scanned.pdf")           # raises — no text layer
except RuntimeError:
    result = get_chunks("scanned.pdf", list_images=True)  # succeeds
    pages = [c for c in result.chunks if c["content_type"] == "image"]
    # → one PNG per page, ready for OCR downstream
    result.images["image_p1_1.png"]              # bytes for the first page

Legacy .doc too old

Only Word 97–2003 .doc files are supported. A pre-Word 97 binary raises RuntimeError: Pre-Word 97 .doc files are not supported. Convert to .docx first. — convert it (e.g. via LibreOffice) and retry.

HTML that is not UTF-8

An HTML document is decoded using its own declared encoding, so a windows-1251 or iso-8859-6 page reads correctly rather than failing or arriving as mojibake.

The order is:

1. a BOM, if present — decisive
2. valid UTF-8 — if the bytes decode as UTF-8, that wins
3. the document's <meta charset=…> or <meta http-equiv="Content-Type" content="…; charset=…">, read from the first 1 KiB
4. detection — the same ladder .txt uses: BOM-less UTF-16 from the NUL pattern, then a statistical charset detector for 8-bit encodings

Step 3 reads only the first 1 KiB because that is what the HTML standard's prescan specifies. A declaration further into the file is therefore missed by step 3 and settled by step 4, which is why the detector matters: it previously decoded every 8-bit document as Windows-1252 regardless of content, so a windows-1251 page returned mojibake rather than Cyrillic.

Step 2 comes before the declaration on purpose. A file that is valid UTF-8 while declaring something else is mislabelled, and trusting the bytes that actually decode means this behaviour can never change the output of a document that was already correct.

Files other parsers read that we do not

A small number of well-formed files are rejected because the underlying parser does not cover that corner of the format. They fail cleanly with a typed exception — nothing crashes, nothing is silently truncated — but they will not chunk. Verified 2026-08-16 against py-chunks 0.6.2:

The practical guidance is the same as for any parse failure: catch the exception, log the path, and fall back to a converted copy (LibreOffice round-trips all of these). Do not treat a rejection as "the document is empty" — that distinction is what the typed exception exists to give you.