[BUG] Claude Code Session Freeze on Large File Read Error (v2.1.1 - v2.1.3)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

<html><head></head><body><h1>Bug Report: Claude Code Session Freeze on Large File Read Error (v2.1.1 - v2.1.3)</h1>
<h2>Preflight Checklist</h2>
<ul>
<li>[x] I have searched existing issues and this hasn't been reported yet</li>
<li>[x] This is a single bug report</li>
<li>[x] I am using the latest version of Claude Code</li>
</ul>
<h2>Environment</h2>
<ul>
<li><strong>Platform:</strong> Linux</li>
<li><strong>Terminal:</strong> WezTerm</li>
<li><strong>Claude Code Version:</strong> 2.1.2, 2.1.3 (regression from 2.1.0)</li>
<li><strong>Node.js:</strong> v22</li>
</ul>
<h2>Bug Description</h2>
<p>Claude Code completely freezes/hangs when the Read tool encounters a file larger than 256KB and returns an error. The session becomes unresponsive - no keyboard input works, Ctrl+C is ignored, and the only recovery is to force-kill the terminal.</p>
<p><strong>Key observation:</strong> Version 2.1.0 handles this gracefully (shows error and continues). Versions 2.1.2 and 2.1.3 freeze completely.</p>
<h2>Steps to Reproduce</h2>
<ol>
<li>Start Claude Code v2.1.1 or later</li>
<li>Have a file larger than 256KB in your project (e.g., a 600KB+ source file)</li>
<li>Ask Claude to analyze or read the file</li>
<li>Claude attempts to use the Read tool</li>
<li>Read tool returns error: <code>Error: File content (XXX.XKB) exceeds maximum allowed size (256KB)</code></li>
<li><strong>Session freezes completely</strong> - no further input possible</li>
</ol>
<h2>Expected Behavior</h2>
<p>Claude Code should:</p>
<ol>
<li>Display the error message to the user</li>
<li>Suggest alternatives (use <code>head</code>, <code>tail</code>, <code>grep</code>, or <code>offset</code>/<code>limit</code> parameters)</li>
<li><strong>Continue accepting input normally</strong></li>
</ol>
<p>This is how v2.1.0 behaves.</p>
<h2>Actual Behavior</h2>
<p>After the Read tool error:</p>
<ul>
<li>Terminal becomes completely unresponsive</li>
<li>Cannot type any input</li>
<li>Ctrl+C does not interrupt</li>
<li>Escape key does not work</li>
<li>Session is stuck on "Perusing..." or similar state</li>
<li>Only recovery is force-killing the process/terminal</li>
</ul>
<h2>Console Output Before Freeze</h2>
<pre><code>● Read(/tmp/largefile.txt)
⎿ Error: File content (600.0KB) exceeds maximum allowed size (256KB). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.
● Bash(wc -l /tmp/largefile.txt &amp;&amp; head -100 /tmp/largefile.txt)
⎿ Running…

• Perusing… (ctrl+c to interrupt · 34s · ↓ 1.3k tokens · thought for 1s)

[FROZEN - no further response]
</code></pre>
<h2>Regression Information</h2>

Version | Status
-- | --
2.1.0 | ✅ Works - handles error gracefully
2.1.1 | ❓ Not tested
2.1.2 | ❌ Freezes
2.1.3 | ❌ Freezes

<h2>Workaround</h2>
<p>Pin to version 2.1.0:</p>
<pre><code class="language-bash">npm install -g @anthropic-ai/claude-code@2.1.0
</code></pre>
<p>And disable auto-updater:</p>
<pre><code class="language-bash">export DISABLE_AUTOUPDATER=1
</code></pre>
<h2>Related Issues</h2>
<ul>
<li>#7565 - Shows same 256KB error but different symptoms (closed as not planned)</li>
<li>#10481 - ReadFileUtf8 I/O block causing freeze (v2.0.28, macOS)</li>
<li>#1452 - Large file mention hangs Claude Code</li>
</ul>
<h2>Additional Context</h2>
<p>This appears to be a regression in error handling for the Read tool. The 256KB limit itself is fine, but the error path seems to leave Claude Code in an unrecoverable state in versions after 2.1.0.</p></body></html>

What Should Happen?

<html><head></head><body><h2>What's Wrong? (Bug Description)</h2>
<p>Claude Code completely freezes/hangs when the Read tool encounters a file larger than 256KB and returns an error. The session becomes unresponsive - no keyboard input works, Ctrl+C is ignored, and the only recovery is to force-kill the terminal.</p>
<p><strong>Key observation:</strong> Version 2.1.0 handles this gracefully (shows error and continues). Versions 2.1.2 and 2.1.3 freeze completely.</p>
<h3>Console Output Before Freeze</h3>
<pre><code>● Read(/tmp/largefile.txt)
⎿ Error: File content (600.0KB) exceeds maximum allowed size (256KB). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.
● Bash(wc -l /tmp/largefile.txt &amp;&amp; head -100 /tmp/largefile.txt)
⎿ Running…

• Perusing… (ctrl+c to interrupt · 34s · ↓ 1.3k tokens · thought for 1s)

[FROZEN - no further response]
</code></pre>
<p>After the Read tool error:</p>
<ul>
<li>Terminal becomes completely unresponsive</li>
<li>Cannot type any input</li>
<li>Ctrl+C does not interrupt</li>
<li>Escape key does not work</li>
<li>Session is stuck on "Perusing..." or similar state</li>
<li>Only recovery is force-killing the process/terminal</li>
</ul>
<h3>Regression Information</h3>

Version | Status
-- | --
2.1.0 | ✅ Works - handles error gracefully
2.1.1 | ❓ Not tested
2.1.2 | ❌ Freezes
2.1.3 | ❌ Freezes

<hr>
<h2>What should happen? (Expected Behavior)</h2>
<p>When the Read tool encounters a file larger than 256KB, Claude Code should:</p>
<ol>
<li>Display the error message to the user</li>
<li>Suggest alternatives (use <code>head</code>, <code>tail</code>, <code>grep</code>, or <code>offset</code>/<code>limit</code> parameters)</li>
<li><strong>Continue accepting input normally</strong> and remain responsive</li>
</ol>
<p>This is the behavior observed in v2.1.0 - the error is shown but the session remains fully functional.</p>
<hr>
<h2>Steps to Reproduce</h2>
<ol>
<li>Start Claude Code v2.1.2 or v2.1.3</li>
<li>Have a file larger than 256KB in your project (e.g., a 600KB+ source file)</li>
<li>Ask Claude to analyze or read the file</li>
<li>Claude attempts to use the Read tool</li>
<li>Read tool returns error about file exceeding 256KB limit</li>
<li>Session freezes completely - no further input possible</li>
</ol>
<hr>
<h2>Claude Code Version</h2>
<p>2.1.3</p>
<hr>
<h2>Platform (select one)</h2>
<p>Anthropic API</p>
<hr>
<h2>Operating System</h2>
<p>Linux</p>
<hr>
<h2>Terminal</h2>
<p>WezTerm</p>
<hr>
<h2>Additional Context / Workaround</h2>
<p><strong>Workaround:</strong> Pin to version 2.1.0 and disable auto-updater:</p>
<pre><code class="language-bash">npm install -g @anthropic-ai/claude-code@2.1.0
export DISABLE_AUTOUPDATER=1
</code></pre>
<p><strong>Related Issues:</strong></p>
<ul>
<li>#7565 - Shows same 256KB error but different symptoms</li>
<li>#10481 - ReadFileUtf8 I/O block causing freeze (v2.0.28)</li>
<li>#1452 - Large file mention hangs Claude Code</li>
</ul>
<p>This appears to be a regression in error handling for the Read tool. The 256KB limit itself is fine, but the error path seems to leave Claude Code in an unrecoverable state in versions after 2.1.0.</p></body></html>

Error Messages/Logs

2026-01-09T22:35:28.612Z [DEBUG] Getting matching hook commands for PreToolUse with query: Read
2026-01-09T22:35:28.612Z [DEBUG] Found 0 hook matchers in settings
2026-01-09T22:35:28.612Z [DEBUG] Matched 0 unique hooks for query "Read" (0 before deduplication)
2026-01-09T22:35:28.627Z [ERROR] Error: Error: File content (629.1KB) exceeds maximum allowed size (256KB). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.
    at Object.call (file:///home/node/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1680:973)
    at VY7 (file:///home/node/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:3362:27242)
2026-01-09T22:35:28.635Z [DEBUG] Getting matching hook commands for PostToolUseFailure with query: Read
2026-01-09T22:35:28.635Z [DEBUG] Found 0 hook matchers in settings
2026-01-09T22:35:28.635Z [DEBUG] Matched 0 unique hooks for query "Read" (0 before deduplication)
2026-01-09T22:35:28.649Z [DEBUG] LSP Diagnostics: getLSPDiagnosticAttachments called
2026-01-09T22:35:28.649Z [DEBUG] LSP Diagnostics: Checking registry - 0 pending
2026-01-09T22:35:28.649Z [DEBUG] Hooks: Found 0 total hooks in registry
2026-01-09T22:35:28.649Z [DEBUG] Hooks: checkForNewResponses returning 0 responses


Session froze after this point - no further log entries, terminal completely unresponsive.

Steps to Reproduce

1. Install Claude Code v2.1.2 or v2.1.3:

``bash
npm install -g @anthropic-ai/claude-code@2.1.3
``

1. Create a large test file (>256KB):

``bash
mkdir test-project && cd test-project
yes "This is a line of text to make the file large enough to trigger the bug." | head -10000 > largefile.txt
ls -lh largefile.txt # Should show ~600KB+
``

1. Start Claude Code:

``bash
claude
``

1. Ask Claude to read the file:

``
Please read and analyze largefile.txt
``

1. Claude will attempt to use the Read tool and receive the error:

``
Error: File content (XXX.XKB) exceeds maximum allowed size (256KB)
``

1. Observe: After the error appears, the session freezes completely:

• Cannot type any input
• Ctrl+C does not work
• Escape key does not work
• Must force-kill the terminal to exit

Note: This issue does NOT occur in v2.1.0 - the error is displayed but the session remains responsive.

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.1.0

Claude Code Version

2.1.3

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

Workaround: Pin to version 2.1.0 and disable auto-updater:
npm install -g @anthropic-ai/claude-code@2.1.0
export DISABLE_AUTOUPDATER=1

Related Issues:

• #7565 - Shows same 256KB error but different symptoms
• #10481 - ReadFileUtf8 I/O block causing freeze (v2.0.28)
• #1452 - Large file mention hangs Claude Code

The 256KB file size limit itself is fine - the issue is that the error handling path leaves the UI in an unrecoverable frozen state. In v2.1.0, the same error is displayed but the session remains fully responsive.