Read tool: PDF handler caches a failed pdftoppm resolution permanently for the process lifetime, even with a correct PATH

Open 💬 0 comments Opened Jul 7, 2026 by stefano-tensortech-co

Environment:

  • Claude Code v2.1.202
  • Windows 11
  • poppler installed, pdftoppm.exe present and working standalone
  • PATH confirmed clean and correct (verified via Get-Command pdftoppm.exe and by inspecting the running process's own environment)

Description:
The Read tool's PDF handler resolves pdftoppm once per process (apparently via where.exe against the process's own process.env) and caches the result -- including a null/not-found result -- for the lifetime of that process. If the very first resolution attempt races process startup (i.e. fires before the process's PATH is fully assembled), the null result is cached permanently. Every subsequent attempt to Read a PDF in that session then fails with "pdftoppm is not installed," regardless of PATH being correct by the time of the actual call.

Repro steps:

  1. Ensure pdftoppm.exe is installed and resolvable via PATH (confirm with Get-Command pdftoppm.exe or equivalent).
  2. Start a fresh Claude Code session/process.
  3. As close to immediately as possible, ask Claude to Read a PDF file (e.g. Read <path>.pdf, pages "1-2").
  4. Observe: pdftoppm is not installed. Install poppler-utils... even though the binary resolves fine standalone in the same shell, in the same process's environment.
  5. Confirm the process is genuinely a single fresh instance (Get-Process -Name claude | Select Id, StartTime) with no lingering old process -- ruling out a stale-process explanation.
  6. Every subsequent PDF Read in that same session continues to fail identically, with no recovery, even without any PATH change.

Expected: PDF reads succeed when pdftoppm is genuinely resolvable, or the resolver retries on a prior null result rather than caching it forever.

Actual: A single early race permanently disables PDF reading for the rest of the process's life.

Workaround in use: render pages to PNG via pdftoppm.exe -png -r <dpi> <file>.pdf <prefix> in a separate shell call, then Read the resulting PNGs directly -- this avoids the Read tool's internal PDF-handling code path entirely.

View original on GitHub ↗