[BUG] Terminal crash on EISDIR error when Read tool used on directory (Windows)

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?

Bug Report: Claude Code Terminal Crash on EISDIR Error (Windows)

Summary

Claude Code terminal unexpectedly disconnects/crashes when the AI assistant attempts to use the Read tool on a directory path instead of a file path on Windows systems. This results in an EISDIR (illegal operation on a directory) error that terminates the entire Claude Code session, requiring manual restart.

Environment Information

Operating System:

• Platform: Windows 11 (Build 26200.7019)
• Architecture: x64

Runtime:

• Node.js: v22.20.0
• npm: 10.9.3
• Claude Code: Latest version (npm global installation)

Installation Method:

• npm global: @anthropic-ai/claude-code

Bug Description

What Happens

When Claude Code's AI assistant attempts to read a directory path using the Read tool (instead of a file path), the following sequence occurs:

1. User grants permission for file operation
2. Assistant executes Read tool with a directory path
3. Node.js throws EISDIR error: "Error: EISDIR: illegal operation on a directory, read"
4. Claude Code terminal immediately crashes/disconnects
5. User must manually restart Claude Code to continue

Expected Behavior

The Read tool should:

• Validate that the path is a file before attempting to read
• Return a graceful error message to the assistant if path is a directory
• Not crash the entire terminal session
• Suggest using appropriate tools (e.g., Bash with ls or dir) for directory operations

Actual Behavior

• Terminal session terminates completely
• All context is lost
• User must restart claude command
• No graceful error handling

Reproduction Steps

Scenario 1: File Exploration Task

1. Start Claude Code in any directory: claude
2. Ask the assistant to explore project files or edit configurations
3. Grant permission when the assistant requests file access
4. The assistant may accidentally attempt to read a directory instead of a file
5. Observe terminal crash with EISDIR error

Scenario 2: Permission Grant Flow

1. User provides a task requiring file operations
2. Assistant requests permission to read files
3. User approves (Option 2 in permission prompt)
4. If the assistant passes a directory path to Read tool
5. Immediate crash occurs post-permission grant

Evidence from Debug Logs

Debug log analysis revealed the following error trace:

[DEBUG] executePreToolHooks called for tool: Read
[DEBUG] Skipping PreToolUse:Read hook execution - workspace trust not accepted
[ERROR] Error: Error: EISDIR: illegal operation on a directory, read
    at Module.readFileSync (node:fs:441:20)
    at Object.readFileSync (file:///[...]/node_modules/@anthropic-ai/claude-code/cli.js:9:299)
    at Zf2 (file:///[...]/node_modules/@anthropic-ai/claude-code/cli.js:3566:956)
    at Object.call (file:///[...]/node_modules/@anthropic-ai/claude-code/cli.js:3398:947)
    at call.next (<anonymous>)
    at aj6 (file:///[...]/node_modules/@anthropic-ai/claude-code/cli.js:2693:65802)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)

Timeline of Events:

• PreToolUse hook called for Read tool
• No path validation performed
• fs.readFileSync() called on directory path
• EISDIR error thrown
• Session terminates immediately

Root Cause Analysis

Technical Details

Issue Location:
The error originates in the Read tool implementation within Claude Code's CLI:

• Direct call to Node.js fs.readFileSync() without path validation
• No pre-check using fs.statSync().isDirectory()
• Missing error boundary for file system operations

Why It Crashes:

1. The Read tool implementation uses fs.readFileSync() directly
2. When passed a directory path, Node.js throws EISDIR error
3. This error is not caught by a try-catch block
4. Uncaught exception propagates and terminates the process
5. Claude Code session ends abruptly

Platform-Specific Behavior

This appears to be Windows-specific:

• Windows file system error handling differs from Unix-based systems
• The same error might be handled gracefully on macOS/Linux
• Requires cross-platform testing for confirmation

Impact Assessment

Severity: High

• Complete loss of session context
• Interrupts workflow requiring full restart
• Can occur during normal operations after permission is granted

Frequency: Medium

• Occurs when AI assistant makes path resolution mistakes
• More common during file exploration and configuration tasks
• Intermittent but consistently reproducible

User Impact:

• Frustrating user experience
• Loss of conversation history and context
• Time wasted restarting and re-explaining tasks
• Reduced trust in granting permissions

Proposed Solutions

Solution 1: Pre-Validation (Recommended)

Add path validation in the Read tool before calling readFileSync():

// Proposed implementation for Read tool
async function readFile(filePath) {
  try {
    // Validate path exists
    if (!fs.existsSync(filePath)) {
      return {
        error: `File not found: ${filePath}`,
        recoverable: true
      };
    }

    // Check if path is a directory
    const stats = fs.statSync(filePath);
    if (stats.isDirectory()) {
      return {
        error: `Cannot read '${filePath}': Path is a directory.`,
        suggestion: "Use Glob pattern matching or Bash tool with 'ls'/'dir' for directories.",
        recoverable: true
      };
    }

    // Proceed with file read
    const content = fs.readFileSync(filePath, 'utf-8');
    return { success: true, content };

  } catch (error) {
    // Graceful error handling
    return {
      error: error.message,
      code: error.code,
      recoverable: true
    };
  }
}

Benefits:

• Prevents crash entirely
• Provides helpful error messages to AI
• Guides AI to use correct tools
• Maintains session continuity

Solution 2: Global Error Boundary

Wrap all tool executions in error handling that prevents process termination:

async function executeToolSafely(toolName, params) {
  try {
    const result = await executeTool(toolName, params);
    return result;
  } catch (error) {
    console.error(`[ERROR] Tool '${toolName}' failed: ${error.message}`);

    // Return error to AI instead of crashing
    return {
      error: true,
      message: error.message,
      code: error.code,
      suggestion: "Try using a different tool or approach"
    };
  }
}

Solution 3: Enhanced AI Instructions

Update system prompt with explicit warnings:

• "CRITICAL: Never use Read tool on directory paths"
• "Always verify file paths with Glob before reading"
• "Use Bash tool for directory operations"

Workarounds

For Users:

1. Save important context before granting permissions
2. If crash occurs, restart immediately: claude
3. Consider reporting crashes when they happen
4. Monitor AI's intended actions in permission prompts

For AI Assistant:

1. Always use Glob to verify paths are files first
2. Never pass directory paths to Read tool
3. Use Bash tool with dir/ls for directory operations
4. Validate paths before requesting permissions

Testing Recommendations

Cross-Platform Testing Needed:

• [ ] Windows 10 (various builds)
• [ ] Windows 11 (various builds)
• [ ] macOS (Intel and Apple Silicon)
• [ ] Linux (Ubuntu, Fedora, Arch)
• [ ] WSL (Windows Subsystem for Linux)

Node.js Version Testing:

• [ ] Node.js v18.x (LTS)
• [ ] Node.js v20.x (LTS)
• [ ] Node.js v22.x (Current)

Additional Information

Related Components

• File system operations in other tools (Write, Edit)
• Permission system behavior
• Error handling in tool execution pipeline

Configuration Details

• Working Directory: Standard user home directory
• Bash Path: Git Bash installation on Windows
• Permission Mode: Granular allow list configuration

---

Technical Analysis Summary

This bug represents a critical gap in error handling within the file system tool implementation. The root cause is the absence of defensive programming practices:

1. No Input Validation - Paths are not validated before use
2. No Error Boundaries - Exceptions terminate the process
3. No Graceful Degradation - No fallback when operations fail

The fix is straightforward but requires attention to:

• Type checking (file vs directory)
• Error catching and handling
• User-friendly error messages
• AI assistant guidance for alternative approaches

---

Checklist

• [x] Bug is reproducible
• [x] Debug logs analyzed
• [x] System information documented
• [x] Root cause identified
• [x] Solutions proposed with code examples
• [x] Workarounds documented
• [ ] Cross-platform testing completed
• [x] Ready for GitHub submission

---

Report prepared by: Developer with 6 months of hands-on coding experience, specializing in full-stack web development with Node.js and Windows development environments

Methodology: Systematic debugging using debug log analysis, error trace investigation, and root cause analysis

Tools Used: This report was generated with assistance from Claude AI (Claude Sonnet 4.5, model: claude-sonnet-4-5-20250929) for technical analysis and documentation

Date: November 3, 2025

What Should Happen?

Key Difference

| Expected | Actual (Bug) |
|-------------------------|--------------------|
| Graceful error handling | Uncaught exception |
| Helpful error message | Terminal crash |
| Session continues | Session terminates |
| AI learns & adapts | User must restart |

Error Messages/Logs

PS C:\Users\[USER]> [Terminal returns to PowerShell prompt - Claude Code has crashed]

  ---
  Additional Context from Debug Log:

  [DEBUG] File C:\Users\[USER]\.claude.json written atomically
  [DEBUG] Telemetry flushed successfully
  [DEBUG] Writing to temp file: C:\Users\[USER]\.claude.json.tmp.[PID].[timestamp]
  [ERROR] Error: Error: EISDIR: illegal operation on a directory, read
  [Session terminates]

  ---
  What This Shows:

  - ✅ Error Type: EISDIR (illegal operation on a directory)
  - ✅ Root Cause: Module.readFileSync at node:fs:441:20
  - ✅ Location: Read tool implementation in cli.js
  - ✅ Result: Uncaught exception → Process termination
  - ✅ Platform: Windows (PowerShell terminal)

Steps to Reproduce

# Create test dir
mkdir test-dir && cd test-dir && mkdir subdir && echo "test" > file.txt

# Start Claude
claude

# Prompt: "Please read the subdir file"
# Grant permission
# Observe crash

---
What Makes This Bug Occur

The bug triggers when:

1. ✅ User asks Claude to work with files/directories
2. ✅ User grants permission for file operations
3. ✅ Claude's AI interprets a directory path as a file path
4. ✅ Read tool receives directory path instead of file path
5. ✅ fs.readFileSync() throws EISDIR error
6. ✅ Error is uncaught → Terminal crashes

---
Files Needed (None!)

This bug requires no special files or code - just:

• Any directory in the filesystem
• Claude Code installation
• A prompt that might cause confusion between files and directories

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.31

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_