One of the research agents in my pipeline came back with a short, confident report about a government statistics PDF:
image PDF, cannot be machine-read
That line didn't stay a report. It went into the file I use as the single source of truth for numbers I'm allowed to quote. Next to one statistic it left a caveat: not checked against the original, confidence "probably". A second-hand article quoted a different value for the same statistic, and because the original "couldn't be read", nobody could say which one was right.
So I had a number I couldn't stand behind, a conflicting number I couldn't rule out, and a reason for both that sounded like a property of the document: it's a scan.
It wasn't a scan. The PDF had a perfectly good text layer. One extraction tool couldn't decode it, and a different one read the whole table on the first try. Once I had the table, the "conflict" was settled by the very first read: the two numbers came from different fiscal years. Neither one was wrong.
This post covers what actually went on inside that PDF, the two small traps I hit even after switching tools, and the part I care about most: how "this tool returned nothing" quietly turned into "this information doesn't exist" on its way downstream.
What I ran
When I picked this up myself, I started where most people would:
# what actually worked, in order curl -s -o x.pdf "<the PDF URL>" pdftotext -layout x.pdf - # -> empty (the trap) python -c "import pypdf; print(pypdf.PdfReader('x.pdf').pages[0].extract_text())" # -> text pdftotext printed nothing. No error that I noticed, no complaint about the font, no hint that something had gone wrong. Just an empty result.
A web-fetch tool that turns pages into markdown did no better. It reported the file as binary data it couldn't read.
Then pypdf returned the table. Every row, every column, every number.
So the same file gave three answers:
| Route | What it said |
|---|---|
pdftotext | nothing at all |
| web fetch → markdown | "binary, can't read this" |
pypdf extract_text() | the full table |
If you only ran the first two, "it's an image PDF" is a reasonable guess. It's also wrong, and the third row proves it.
Why a PDF with real text can look empty
A text layer in a PDF isn't simply "the characters". It's a sequence of codes drawn with a font, plus (if you're lucky) enough information to turn those codes back into Unicode.
For most Western PDFs, that step is boring. The codes are close to something standard, or the file carries an explicit mapping, and every extractor gets it right.
East Asian PDFs often use CID-keyed fonts. The page content holds character codes in some legacy encoding. A CMap resource tells the reader how those codes relate to glyphs in a big character collection. This file declared its encoding as:
/90msp-RKSJ-H That name looks like line noise, but it's readable once you know the parts. Adobe's own note on CMap names explains most of it: RKSJ stands for single-byte Roman, half-width Katakana and Shift-JIS. 90ms is the 1990 JIS character set with Microsoft's extensions. The p marks a variant where the single-byte ASCII range maps to proportional Latin glyphs. The trailing H I read as horizontal writing, by the usual CMap naming pattern; that part isn't from the note I checked. In plain terms: Shift-JIS text, the Windows flavour.
To get text out, an extractor has to recognise that CMap name and know how to go from those Shift-JIS codes to Unicode. If it doesn't, it has a few options. It can raise an error, guess, or drop the characters. Only the first option tells you anything.
I don't actually know why pdftotext came back empty on that machine. My best guess is that its build didn't have the CMap data for that encoding, so there was nothing to map the codes to. I didn't verify that, and I'd rather say so than make up a neat explanation. What matters for this post is that the result looked exactly like a PDF with no text layer, and it wasn't one.
If I were diagnosing this again, I'd check the fonts before deciding anything. pdffonts (from the same poppler toolset as pdftotext) lists each font with its type and encoding. A CID font with a named Shift-JIS CMap is a strong hint that the text exists and only the decoding is in question. I didn't run it during the original incident, so treat it as a suggestion, not something I've tested on this file.
Two traps after switching tools
Switching to pypdf wasn't the end of it. There were two more chances to give up for the wrong reason.
Trap 1: a warning that reads like a failure
pypdf printed this while extracting:
Advanced encoding /90msp-RKSJ-H not implemented yet If you skim that line, the conclusion writes itself: pypdf doesn't support this encoding either, extraction failed, back to "it's a scan".
But the text came back anyway. Whatever the message meant, it wasn't a failure. My guess is that the library had no dedicated handler for that exact CMap name and fell back to something close enough, but the warning I saw didn't say so, and I didn't dig into the internals. What I can say is that the table came out.
The rule I took from it: judge the extraction by its return value, not by its log output. Check the length of the string. Check whether a few cells you can see on screen are actually in it. A warning about encoding means "pay attention", not "stop".
One caveat, because libraries move. That warning came from the version I had at the time. Looking at pypdf's current source today, the message is logged at error level and now says which fallback it's using. The plain 90ms-RKSJ-H encoding (without the p) now maps directly to cp932, the Windows Shift-JIS code page. The p variant this file used still isn't listed there. So on a current install you might see a different message, or none, or a better result. That supports the point. Don't build your conclusion on the exact wording of a library's log line.
Trap 2: the crash that isn't the extractor's fault
On Windows, printing the extracted text straight to the console dies with something like:
UnicodeEncodeError: 'cp932' codec can't encode character ... At a glance, that's another "the Japanese text is broken" signal. It isn't. The extraction had succeeded. The crash happened afterwards, when Python tried to write the result to a console using the system's legacy code page, and some character in the output had no slot in that code page.
That's a display failure, not an extraction failure. The fix is to never route the text through the console at all:
import pypdf t = pypdf.PdfReader('x.pdf').pages[0].extract_text() open('x.txt', 'w', encoding='utf-8').write(t) print('len:', len(t)) Write to a UTF-8 file, print only the length, and open the file in an editor that won't guess the encoding for you. Now the one thing on the console is a number you can check, and the text itself never has to pass through a code page that can't hold it.
Notice the pattern so far. Every one of these signals pointed the same way:
-
pdftotextprinted nothing - the fetch tool said "binary"
-
pypdfprinted an encoding warning -
print()threw an encoding error
Each one, read alone, says "this document can't be read". All four were wrong for the same reason: they were telling me about a tool or a step in the pipeline, not about the document.
The damage wasn't the PDF. It was the sentence.
Losing a few minutes to an unreadable PDF is normal. What bothered me was where the wrong conclusion ended up and what it blocked.
Walk through what happened to that one line:
- A tool returned nothing.
- The agent wrote "image PDF, cannot be machine-read". That's a statement about the document, not about the tool.
- That statement went into my facts file as a caveat on a real number: unverified, confidence "probably".
- Because the source was "unreadable", nobody went back to it. Why would you retry a scan?
- A second-hand article with a different value now looked like it might be right, and I had no way to rule it out.
- Downstream writing that wanted to use the number had to hedge it or leave it out.
So a primary source that existed, was public, and was fully readable got treated as unusable. My own pipeline had decided it couldn't be trusted, and the record made that decision look settled.
The key move is step 2. The tool's limit got reworded as a property of the thing being examined. Once that happens, the uncertainty doesn't look like "we haven't found the right tool yet". It looks like a fact about the world, and facts about the world don't get retried.
I'd seen the same shape once before, in a different form. An agent searched for something, found nothing, and reported that the thing didn't exist. It did exist. Different tool, same mistake: an empty result written down as an absence.
What I changed
Reports name the route, not the property
This is the change I'd make first in any pipeline that has agents (or people) reporting on sources:
- ❌ "Image PDF, cannot be machine-read. Value not verified."
- ✅ "
pdftotextreturned empty.pypdfnot tried. Value not verified."
The two versions have the same outcome today: the value isn't verified. The difference is what they let the next person do.
The first sentence closes the case. It names a cause, the cause sounds permanent, and nobody's job is to argue with it.
The second one leaves the case open. It records which path failed and which paths haven't been tried. Anyone reading it, including me a week later, can see the obvious next step, and the uncertainty is labelled honestly as "incomplete", not "impossible".
If I had to compress it into one line for a style guide: write down which path failed, not what the file is.
"Not there" needs two different routes
The rule I now apply before anything gets recorded as unreadable, missing, or non-existent: try at least two routes that work in different ways, and only then say it isn't there.
"Different" matters. Running pdftotext with other flags is still the same decoder. A second web-fetch tool that might sit on a similar converter isn't much of a second opinion either. pypdf counted as a second route here because it's a separate implementation with its own encoding handling. If both had come back empty, then "probably a scan" would be a fair working guess, and the next step would be rendering a page as an image and reading it visually, or looking for an HTML or spreadsheet version of the same table.
Agents without a shell must escalate, not conclude
The same pipeline has an agent whose job is to keep checking documents like this one. It has web-fetch and file tools, but no shell, so it can't run pypdf at all. That's on purpose. I keep agents that read untrusted web content away from a shell, and I'm not going to change that to make PDFs easier.
But it means the honest answer from an agent like that is never "this is an image PDF". The honest answer is "I can't read this PDF with the tools I have". So its instructions now say that explicitly. When a PDF comes back empty or as "binary", don't classify the document. Report that reading it needs a text-extraction route outside your tools, and hand it up to a session that has one.
That turns a dead end into a handoff. The work still gets done, just by a part of the system that can actually do it, and nobody pretends the limit belongs to the PDF.
The facts file gets the original, not a guess
Once pypdf had the table, I could check the stored number against the original directly. It matched. The second-hand number turned out to be from an earlier fiscal year. Two correct numbers, two different points in time.
My facts file is protected: changes need explicit human approval. So instead of editing it in the same session, I wrote up a change request: drop the "cannot be read" caveat, raise the confidence, add the original URL, and note which year each number belongs to. The point of that file is that what's in it was checked against a primary source. That's exactly the standard the original caveat failed, so it shouldn't be quietly patched either.
A short checklist
Here's what I run through now when a PDF "can't be read":
- [ ] Did more than one decoder try? If
pdftotextis empty, trypypdf(or another independent library) before saying anything about the document. - [ ] What does the font list say? A CID font with a named CMap like
90msp-RKSJ-Hsuggests the text is there and only the decoding is in question. (Suggested, not tested on this file.) - [ ] Did I judge by the return value? Length of the string, plus a few values you can see on the rendered page. Not the log output.
- [ ] Did the text ever touch the console? On Windows, write to a UTF-8 file. A
UnicodeEncodeErroronprint()isn't an extraction failure. - [ ] Does the report name the route? "X returned empty, Y not tried", never "unreadable" or "image PDF" on its own.
- [ ] Can the agent that hit the wall actually try another route? If not, its job is to escalate, not to conclude.
What this changed for me
The bug here wasn't really in pdftotext. Tools have limits, and an empty result from one decoder on a Shift-JIS CID font isn't surprising once you know what's in the file.
The bug was one sentence that turned a tool's limit into a fact about the world, and then a pipeline that trusted the sentence more than it trusted the source. An empty result tells you about the reader. It tells you nothing about the page until something else has read it too.
I'm building a code review tool, and the same idea runs through it: when it holds back lower-priority remarks, it counts them and shows the count on the review, so "nothing shown" never gets read as "nothing found". If that sounds useful: getdevreview.com.

