[BUG] Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS)

Claude Code 2.0.28 Complete UI Freeze - ReadFileUtf8 I/O Block (macOS)

Summary

Claude Code terminal completely frozen - cannot type, process idle at 0% CPU, stuck waiting on file I/O operation. Process appears "alive" but UI is completely unresponsive. All 8853 samples over 10 seconds show process blocked in ReadFileUtf8.

Environment

• OS: macOS 26.0.1 (25A362)
• Node: /opt/homebrew/Cellar/node/24.10.0/bin/node (v24.10.0)
• Claude Code: 2.0.28
• Platform: darwin (ARM64)
• PID: 69856
• Session Start: 2025-10-28 01:53 AM EDT
• Duration at freeze: ~12 minutes
• Memory: 978MB RSS (978752 KB)
• CPU: 0.0% (idle/blocked on I/O)

Bug Description

Claude Code terminal becomes completely unresponsive during normal usage. Process appears alive but:

• Cannot type - keyboard input ignored
• Cannot Ctrl+C - interrupt signals ignored
• Cannot interact - UI completely frozen
• 0% CPU - process not doing any work
• Blocked on I/O - waiting for file read to complete

Critical Impact: User loses complete control of terminal session. Only recovery is force-kill from Activity Monitor.

Root Cause Analysis

CPU Sample Evidence (10 seconds, 8853 samples)

Bottleneck: 100% of samples in ReadFileUtf8

All 8853 samples show identical stack:

node::Start
  → node::NodeMainInstance::Run
    → node::SpinEventLoopInternal
      → uv_run (libuv event loop)
        → Builtins_RunMicrotasks (V8 promise chain)
          → PromiseFulfillReactionJob
            → AsyncFunctionAwaitResolveClosure
              → AsyncGeneratorPrototypeNext
                → AsyncGeneratorResumeNext
                  → InterpreterEntryTrampoline
                    → CallApiCallbackGeneric
                      → node::fs::ReadFileUtf8  ← BLOCKED HERE

What this means:

• Claude Code called readFileSync() or similar synchronous file operation
• File read is blocking (waiting for I/O completion)
• Event loop is blocked - UI cannot process input
• No timeout mechanism - can wait indefinitely
• Process appears "alive" but completely frozen

I/O Analysis

Possible causes of I/O block:

1. Network filesystem - file on slow/unresponsive network mount
2. Large file - reading multi-GB file synchronously
3. File lock - another process holding file lock
4. Disk I/O issue - slow disk or I/O errors
5. Deadlock - waiting on resource held by another part of code

Evidence:

• 0% CPU = not processing, just waiting
• All samples identical = completely stuck, no progress
• UI frozen = event loop blocked on synchronous I/O
• Process "alive" = not crashed, just waiting

Steps to Reproduce

Note: Reproduction unclear - appears to happen during normal usage.

1. Start Claude Code 2.0.28 in project directory
2. Work normally (exact trigger unknown)
3. At some point, Claude Code attempts to read a file
4. Read operation blocks indefinitely
5. Terminal becomes completely unresponsive
6. Only recovery: kill -9 <PID>

Characteristics:

• Happens during normal interactive usage
• No obvious trigger or pattern
• Process remains "running" but frozen
• No error messages or recovery

Expected Behavior

• File read operations should have timeouts
• Long operations should be asynchronous (not block UI)
• User should be able to Ctrl+C to interrupt
• Error should be shown if file cannot be read

Actual Behavior

• Synchronous file read blocks indefinitely
• UI completely frozen - cannot type
• Ctrl+C ignored - interrupt doesn't work
• No timeout, no error, no recovery
• Only solution: force kill from Activity Monitor

Impact

• Severity: Critical - complete loss of terminal control
• Frequency: Occasional (trigger unclear)
• Workaround: None - must force-kill process
• Data loss: All session context lost
• User impact: Work stoppage, complete session loss, frustration

Technical Evidence

Process State

PID:     69856
CPU:     0.0% (idle/blocked)
Memory:  978MB RSS
Status:  Blocked on I/O
Runtime: 12+ minutes frozen

Sample Analysis (10s, 8853 samples)

100% of samples: ReadFileUtf8 (blocked on I/O)
  0% doing actual work

Conclusion: Process completely stuck waiting for file I/O to complete
No progress being made - infinite wait

Evidence Files

Gist: https://gist.github.com/kuzmeech/d388717c72287d66e9526dc75c501e7c

Files:

• processes_info.txt - Summary of both frozen processes
• sample_69856_sanitized.txt - Full 10s CPU sample (297 lines, all identical)

Why This Is NOT a Duplicate

Analysis conducted: Reviewed similar hang/freeze/unresponsive issues from past 4 months.

Issue #9404 - "Agent Hangs with Blinking Grey Dot, Terminal Unresponsive"

• Version: v2.0.14 (Oct 12, 16 days ago)
• Symptom: Agent shows "Done" but prompt doesn't return
• Cause: UI synchronization issue - output stream not closing
• Platform: macOS (Warp Terminal)
• Our issue: Complete UI freeze - no agent involved, cannot type anything
• Conclusion: Different - #9404 is post-completion UI issue, ours is I/O blocking

Issue #7455 - "Freezing Issues at Session Resuming after Ctrl+C interruption on Windows"

• Version: v1.0.x (Sep 11, ~6 weeks ago)
• Symptom: claude --continue freezes permanently after Ctrl+C
• Cause: State corruption from interrupt, persists across reinstalls
• Platform: Windows
• Our issue: Fresh session freeze during normal usage on macOS
• Conclusion: Different - #7455 is Windows state corruption, ours is I/O blocking on macOS

Issue #8658 - "Claude Code Execution Hangs and Becomes Unresponsive"

• Version: v2.0.1 (Oct 1, 27 days ago)
• Symptom: Terminal flickering, multiple Claude instances spawning
• Cause: Infinite file-history-snapshot loop (internal bug)
• Platform: macOS
• Our issue: Single process, I/O blocked, no flickering
• Conclusion: Different - #8658 is snapshot loop bug, ours is I/O blocking

Summary Table

| Issue | Version | Age | Platform | Symptom | Root Cause | Status |
|-------|---------|-----|----------|---------|------------|--------|
| #7455 | v1.0.x | 6w | Windows | Resume freeze | State corruption from Ctrl+C | Different OS/trigger |
| #8658 | v2.0.1 | 27d | macOS | Flickering + hang | Snapshot loop | Different mechanism |
| #9404 | v2.0.14 | 16d | macOS | Post-agent hang | UI sync issue | Different scenario |
| This | v2.0.28 | New | macOS | Complete freeze | ReadFileUtf8 I/O block | Unique issue |

Why this is unique:

1. Synchronous I/O blocking - not seen in other reports
2. Complete UI freeze - cannot type, cannot interrupt
3. 0% CPU - idle waiting (not spinning like other issues)
4. Fresh session - not related to resume/continue/state corruption
5. File I/O specific - stuck in ReadFileUtf8, not general freeze

Suggested Fixes

1. Immediate (critical):

• Add timeouts to all file read operations (5-10 second max)
• Use async file I/O instead of synchronous where possible
• Allow Ctrl+C to interrupt file reads
• Add error handling for I/O timeouts

1. Short-term:

• Audit all readFileSync() calls - replace with async
• Add progress indicators for long file operations
• Implement file size limits before reading
• Add diagnostic logging when file reads take >1s

1. Long-term:

• Never block event loop on I/O operations
• Implement worker threads for file operations
• Add watchdog timer to detect frozen event loop
• Provide user feedback during long operations

Related Issues

• #9404 - Agent completion UI hang (v2.0.14, 16d old - different: UI sync issue)
• #7455 - Windows resume freeze (v1.0.x, 6w old - different: Windows state corruption)
• #8658 - Snapshot loop hang (v2.0.1, 27d old - different: infinite loop bug)

Additional Notes

• Critical bug: Complete loss of terminal control
• No workaround: Cannot Ctrl+C, must force-kill
• Data loss: All work in session lost
• User frustration: No feedback, appears broken
• Unclear trigger: Happens during normal usage
• Possibly related to: Large file reads, network filesystems, or slow disk I/O

Debugging Suggestions

To diagnose which file is causing the block:

1. Add logging before every file read operation
2. Add file path and size to logs
3. Track time spent in file operations
4. Add timeout warnings when operation >1s

Request to Anthropic team: Consider adding debug mode that logs all file I/O operations with paths and timings.

---

Evidence available in gist (sanitized, no personal info)