Claude Code crashes when reading large PDF files - tool_use/tool_result block mismatch

This is a disaster and an emergency. It's preventing me from doing real work.
Occuring in pretty much every session I'm running, sooner or later.

I have PostToolUse hooks active - I wonder if that's the culprit?

The PostToolUse output is being sent as USER MESSAGES back to CLAUDE as if I am sending new messages FOR EVERY NEW TOOL USE.

UNACCEPTABLE.

Please somebody from the Claude Code team - reach out if you want help debugging this.

Collection of other similar bug reports:
#8187 #8077 #8201 #8303 #8325 #8425 #8507 #8612 #8652 #8670 #8746 #8763 #8783 #8790 #8817 #8818 #8821 #8847 #8867 (my report) #8887 #8893 #8894 #8895 #8897 #8903

I use /resume command to continue session.

Workaround: Prevent PDF crashes with CLAUDE.md configuration

I've been experiencing the same crash issue when Claude Code tries to read
large PDFs. Found a reliable workaround by adding mandatory instructions to
.claude/CLAUDE.md:

## PDF Processing

# NEVER use the Read tool to open PDF files directly
# ALWAYS extract PDFs to text first using pdftotext via Bash before
processing
# Reading large PDFs can cause crashes and loss of work

The # prefix makes these instructions high-priority and enforceable.

Workflow that works:

1. Use pdftotext via Bash to extract PDF to .txt file first
2. Process the text file instead of the PDF
3. Keep extracted .txt files alongside PDFs for future reference

This completely avoids the crash issue and is actually faster since text
files are easier to search/process. Would be great if this could be built
into Claude Code as a default behavior or at least a warning before
attempting to read large PDFs.

Workaround: Prevent PDF crashes with CLAUDE.md configuration I've been experiencing the same crash issue when Claude Code tries to read large PDFs. Found a reliable workaround by adding mandatory instructions to .claude/CLAUDE.md: ## PDF Processing # NEVER use the Read tool to open PDF files directly # ALWAYS extract PDFs to text first using pdftotext via Bash before processing # Reading large PDFs can cause crashes and loss of work The # prefix makes these instructions high-priority and enforceable. Workflow that works: 1. Use pdftotext via Bash to extract PDF to .txt file first 2. Process the text file instead of the PDF 3. Keep extracted .txt files alongside PDFs for future reference This completely avoids the crash issue and is actually faster since text files are easier to search/process. Would be great if this could be built into Claude Code as a default behavior or at least a warning before attempting to read large PDFs.

Hmm I'm not under the impression that this is due to pdf processing. Do you have hooks enabled?

FWIW @rpcsteve 's workaround is what I've been using for this for the past week. If I /compact I don't have to restart the session.

I have had the same PDF hang issue using claude code with WSL on Windows and on a Linux machine. I have tried splitting the PDFs with rules based on size, and I still had a hang on the smaller split versions. PDF size is not always the problem. My text extraction is 1000% better, and I use the txt version with Note++ for my own viewing, since my extraction preserves the page layout. They really need to fix this issue because Claude keeps walking into the same wall, if you don't know this workaround.

This always happens to me after leaving a thread open for the night and trying to continue the next day

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

I also still experience the same issue

Now having issues with a just 3MB file (with 30 pages).

same for me, please fix 🤞

Additional Data Point: PDF Processing Memory Issues

Summary

Experiencing similar crashes with much smaller PDFs (690kb). The issue isn't just large files.

What I Found

• PDF size: 690kb (extremely small)
• Error: Same fatal memory allocation failure / tool_use/tool_result mismatch
• Workaround: Converting PDF to markdown first works perfectly with zero issues

Key Insight

This suggests the problem is with the PDF parsing library or how it's being used, not actual file size. A 690kb file should never cause heap allocation failures.

Suspected Root Cause

• PDF library loads entire file + dependencies into memory inefficiently
• Possible memory leak in PDF processing pipeline
• Error handling doesn't gracefully catch OOM conditions before fatal crash

Expected Behavior

• Tool should either process the PDF successfully or fail gracefully with clear error message
• Should not cause complete session termination
• Should handle common PDF formats without memory issues

Current Impact

Users forced to manually convert PDFs to other formats before processing, defeating the purpose of native PDF support.

Since I regularly stumble across this and previously even splitting the PDF files manually did not work (and removed the comfort I expect.. :) ) I tried this and at leas in my most recent case it magically made it work after going back with double-escape.

do not read the whole pdf file!!! only use it for reference when needed. it is too large for you.

The tool_use/tool_result mismatch can persist in the session file and keep causing errors on resume. cozempic can scan and repair these:

\\\bash
pip install cozempic
cozempic doctor --fix
\\\

Finds orphaned \tool_result\ blocks where the matching \tool_use\ was lost and removes them safely with backup. We coded this for our own workflow and made it open source. Feedback appreciated.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.