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

[fxpro32]

Preflight Checklist

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

What's Wrong?

Bug Report: Claude Code Session Freeze on Large File Read Error (v2.1.1 - v2.1.3)

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report
• I am using the latest version of Claude Code

Environment

• Platform: Linux
• Terminal: WezTerm
• Claude Code Version: 2.1.2, 2.1.3 (regression from 2.1.0)
• Node.js: v22

Bug Description

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.

Key observation: Version 2.1.0 handles this gracefully (shows error and continues). Versions 2.1.2 and 2.1.3 freeze completely.

Steps to Reproduce

1. Start Claude Code v2.1.1 or later
2. Have a file larger than 256KB in your project (e.g., a 600KB+ source file)
3. Ask Claude to analyze or read the file
4. Claude attempts to use the Read tool
5. Read tool returns error: Error: File content (XXX.XKB) exceeds maximum allowed size (256KB)
6. Session freezes completely - no further input possible

Expected Behavior

Claude Code should:

1. Display the error message to the user
2. Suggest alternatives (use head, tail, grep, or offset/limit parameters)
3. Continue accepting input normally

This is how v2.1.0 behaves.

Actual Behavior

After the Read tool error:

• Terminal becomes completely unresponsive
• Cannot type any input
• Ctrl+C does not interrupt
• Escape key does not work
• Session is stuck on "Perusing..." or similar state
• Only recovery is force-killing the process/terminal

Console Output Before Freeze

● 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 && head -100 /tmp/largefile.txt)
  ⎿  Running…
* Perusing… (ctrl+c to interrupt · 34s · ↓ 1.3k tokens · thought for 1s)
  [FROZEN - no further response]

Regression Information

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

Workaround

Pin to version 2.1.0:

npm install -g @anthropic-ai/claude-code@2.1.0

And disable auto-updater:

export DISABLE_AUTOUPDATER=1

Related Issues

• [Bug] Incorrect Code Insertion Breaks Syntax and Logic Structure #7565 - Shows same 256KB error but different symptoms (closed as not planned)
• [BUG] Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS) #10481 - ReadFileUtf8 I/O block causing freeze (v2.0.28, macOS)
• [BUG] Large file mention hangs claude code #1452 - Large file mention hangs Claude Code

Additional Context

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.

What Should Happen?

What's Wrong? (Bug Description)

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.

Key observation: Version 2.1.0 handles this gracefully (shows error and continues). Versions 2.1.2 and 2.1.3 freeze completely.

Console Output Before Freeze

● 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 && head -100 /tmp/largefile.txt)
  ⎿  Running…
* Perusing… (ctrl+c to interrupt · 34s · ↓ 1.3k tokens · thought for 1s)
  [FROZEN - no further response]

After the Read tool error:

• Terminal becomes completely unresponsive
• Cannot type any input
• Ctrl+C does not interrupt
• Escape key does not work
• Session is stuck on "Perusing..." or similar state
• Only recovery is force-killing the process/terminal

Regression Information

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

---

What should happen? (Expected Behavior)

When the Read tool encounters a file larger than 256KB, Claude Code should:

1. Display the error message to the user
2. Suggest alternatives (use head, tail, grep, or offset/limit parameters)
3. Continue accepting input normally and remain responsive

This is the behavior observed in v2.1.0 - the error is shown but the session remains fully functional.

---

Steps to Reproduce

1. Start Claude Code v2.1.2 or v2.1.3
2. Have a file larger than 256KB in your project (e.g., a 600KB+ source file)
3. Ask Claude to analyze or read the file
4. Claude attempts to use the Read tool
5. Read tool returns error about file exceeding 256KB limit
6. Session freezes completely - no further input possible

---

Claude Code Version

2.1.3

---

Platform (select one)

Anthropic API

---

Operating System

Linux

---

Terminal

WezTerm

---

Additional Context / Workaround

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:

• [Bug] Incorrect Code Insertion Breaks Syntax and Logic Structure #7565 - Shows same 256KB error but different symptoms
• [BUG] Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS) #10481 - ReadFileUtf8 I/O block causing freeze (v2.0.28)
• [BUG] Large file mention hangs claude code #1452 - Large file mention hangs Claude Code

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.

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:

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

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

   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+

3. Start Claude Code:

   claude

4. Ask Claude to read the file:

   Please read and analyze largefile.txt
   

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

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

6. 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:

• [Bug] Incorrect Code Insertion Breaks Syntax and Logic Structure #7565 - Shows same 256KB error but different symptoms
• [BUG] Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS) #10481 - ReadFileUtf8 I/O block causing freeze (v2.0.28)
• [BUG] Large file mention hangs claude code #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.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS) #10481
2. [BUG] Reading large files causes Claude Code to lock up #17295
3. [Bug] Read Tool: Irreversible Session Corruption with Large Files #6780

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[fxpro32]

This is not a duplicate. My issue is a regression specific to v2.1.2/2.1.3 that works correctly in v2.1.0.

• [BUG] Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS) #10481 is v2.0.28 on macOS - different version and platform
• [Bug] Read Tool: Irreversible Session Corruption with Large Files #6780 is from Aug 2025 (v1.0.x) - much older version, different symptoms (session corruption vs UI freeze)

My issue documents a NEW regression where the 256KB error handling freezes the UI in v2.1.2+ but works fine in v2.1.0. The version-specific regression info is valuable for tracking this down.

*** This issue is still present in v2.1.5

[fxpro32]

Update: Issue persists in v2.1.5 and v2.1.7

I wanted to follow up on this issue. I've tested the latest releases and unfortunately the problem remains unresolved:

Version	Status
2.1.0	✅ Works - handles large files gracefully
2.1.1	❓ Not tested
2.1.2	❌ Freezes
2.1.3	❌ Freezes
2.1.5	❌ Still freezes
2.1.7	❌ Still freezes

Additional finding

The issue is particularly severe with very large files exceeding 25,000 lines of code. The session becomes completely unresponsive with no way to recover other than force-killing the terminal.

Version 2.1.0 remains the only version that handles this scenario gracefully - it displays the error message and continues accepting input normally.

I'm still using the workaround of pinning to v2.1.0 with DISABLE_AUTOUPDATER=1, but this is becoming increasingly difficult to maintain as time goes on.

Could this issue please be prioritized? It's a significant regression that blocks normal workflow when working with large codebases.

[fxpro32]

Update: Issue appears to be resolved in v2.1.12

I can confirm this freeze issue no longer occurs in v2.1.12.

After pinning to v2.1.0 as a workaround for several weeks, I've now tested v2.1.12 and the session remains responsive when the Read tool encounters files larger than 256KB. The error is displayed correctly and input continues to work as expected.

Testing environment:

• Platform: Linux (Fedora)
• Terminal: WezTerm
• Claude Code: v2.1.12
• Running in Podman container

Thanks for the fix! This issue can likely be closed.