[BUG] Claude Code crashes with unhandled ENOSPC error when disk space is low

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?

When the system runs low on disk space (<100MB available), Claude Code crashes with an unhandled promise rejection (ENOSPC: no space left on device) during normal operation. The crash occurs while Claude is actively working on a task and attempting to write to the session file or log files.

The error is:

1. Unhandled - causes immediate crash instead of graceful degradation
2. Repeated - the same error stack trace is printed 3 times before exit
3. Not user-friendly - no explanation of what the user can do to fix it
4. No recovery - Claude Code doesn't attempt to save session state or warn about low disk space

What Should Happen?

1. Graceful degradation: Claude Code should detect low disk space and warn the user before it becomes critical
2. Clear error message: Instead of a raw Node.js stack trace, display a human-readable message like: "Disk space is critically low. Please free up space and restart Claude Code."
3. Session preservation: If possible, attempt to save the conversation state before exiting
4. Single error output: Don't repeat the same error stack trace multiple times
5. Proactive warning: Consider checking disk space periodically and warning users before operations fail

Error Messages/Logs

This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason:
Error: ENOSPC: no space left on device, write
    at Object.writeFileSync (node:fs:2425:20)
    at Module.appendFileSync (node:fs:2507:6)
    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:9:1016
    at BK (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:8:33658)
    at Object.appendFileSync (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:9:834)
    at writeFn (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:9:4655)
    at X (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:9:4027)
    at Object.write (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:9:4150)
    at v (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:11:31)
    at Socket.<anonymous> (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3510:4515) {
  errno: -28,
  code: 'ENOSPC',
  syscall: 'write'
}


**Note**: This exact error stack trace was printed 3 times in succession before the process exited.

Steps to Reproduce

1. Fill your disk to near capacity (leave <100MB free space)
2. Start Claude Code: claude
3. Begin a session and make a request that triggers tool use (e.g., file reads, bash commands)
4. Continue working for a few minutes with multiple tool calls
5. Claude Code will crash with the ENOSPC error when attempting to write session data

Alternative reproduction:

1. Create a small RAM disk or loopback filesystem with limited space
2. Set CLAUDE_LOCAL_STATE_DIR to point to this limited filesystem
3. Start Claude Code and begin working
4. The crash will occur when session writes exceed available space

Claude Model

None

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.1

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Root Cause Analysis

The crash originates from appendFileSync in the minified cli.js at line 9. The code path suggests this is the session logging/transcript writing functionality. The error is unhandled because:

1. Synchronous file operations (writeFileSync, appendFileSync) throw errors directly
2. The surrounding code doesn't have try-catch blocks for disk I/O failures
3. The promise rejection handler catches this but has no graceful recovery path

Suggested Fixes

1. Wrap sync file operations in try-catch:

``javascript
try {
fs.appendFileSync(sessionFile, data);
} catch (err) {
if (err.code === 'ENOSPC') {
console.error('\nError: Disk space is full. Please free up space and restart Claude Code.');
// Attempt graceful shutdown
process.exit(1);
}
throw err;
}
``

1. Add proactive disk space checks:

• Check available disk space at startup
• Warn if below a threshold (e.g., 500MB)
• Check periodically during long sessions

1. Consider async writes with queuing:

• Buffer session writes
• Handle failures gracefully without crashing the main process
• Retry with exponential backoff if disk space becomes available

Impact

• Lost work: Users lose their current session without any ability to save state
• Confusion: Raw Node.js stack traces are intimidating to non-developers
• No recovery path: Users have to restart completely after clearing disk space

Environment Details

• Node.js version: (installed via Homebrew)
• Installation path: /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/
• Session directory: ~/.claude/projects/ (default)