[BUG] Startup crash in Docker: ENOSPC from settings file watcher

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?

Starting claude in a Dockerized environment crashes on startup because the CLI tries to watch config files in both $HOME and the current project. In containers with low/immutable inotify limits, this throws ENOSPC and exits instead of degrading gracefully.

What Should Happen?

claude should start normally. If file watching for settings cannot be established, it should warn and continue without hot-reload of config (or use a safe fallback like polling), not crash.

Error Messages/Logs

node:internal/fs/watchers:254
      const error = new UVException({
                    ^

  Error: ENOSPC: System limit for number of file watchers reached, watch '~/.claude/settings.local.json'
      at FSWatcher.<computed> (node:internal/fs/watchers:254:19)
      at watch (node:fs:2539:36)
      at L$A (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7030)
      at oC9 (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7364)
      at A10._watchWithNodeFs (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:8774)
      at A10._handleFile (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:9500)
      at A10._addToNodeFs (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12508)
      at async file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276
      at async Promise.all (index 0)
  Emitted 'error' event on Z10 instance at:
      at Z10._handleError (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:19822)
      at A10._addToNodeFs (file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12605)
      at async file:///usr/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276
      at async Promise.all (index 0) {
    errno: -28,
    syscall: 'watch',
    code: 'ENOSPC',
    path: '~/.claude/settings.local.json',
    filename: '~/.claude/settings.local.json'
  }

  Node.js v24.7.0

Steps to Reproduce

1. In a Docker container with a low/unchangeable inotify limit (common in shared or restricted environments), ensure

the project has .claude/settings.local.json (and/or a settings file under $HOME).

1. Run claude from that project directory.
2. Observe immediate startup failure with ENOSPC.

Claude Model

None

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

1.0.110 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Workaround

• Deleting the settings file(s) lets claude start successfully. This is a bit heavy-handed but confirms watching

config files is non-essential to core function.

Impact

• Blocks use in constrained containers, remote dev workspaces, and some CI images where raising inotify limits is

not possible.

Proposed Fix

• Catch ENOSPC from file watching and continue:
• Log a clear warning and run without config hot-reload.
• Provide --no-config-watch and/or CLAUDE_DISABLE_CONFIG_WATCH=1.
• Optionally fallback to a low-cost polling strategy (or disable watching entirely in Docker if desired).
• Reduce watcher footprint if both $HOME and project config are watched; dedupe and defer watchers until after startup

so an error can be handled non-fatally.

Additional Context

• In many Docker and shared storage setups, increasing fs.inotify.max_user_watches is not feasible. A graceful

degradation path would make claude robust in these environments.