### Preflight Checklist - [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) 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 conta

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

Status Closed — not planned

Maintainer reply None cached

Activity 10 comments · opened Sep 15, 2025 · closed Feb 9, 2026

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

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).

Run claude from that project directory.
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.

View original on GitHub ↗

10 Comments

janmazak · 1 year ago

It happened to me without any docker. I am using claude without adding settings of my own in a primitive way on Ubuntu 24.04.03. It is not new, happened several weeks ago once.

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

Error: EMFILE: too many open files, watch '.../.claude/settings.local.json'
    at FSWatcher.<computed> (node:internal/fs/watchers:254:19)
    at watch (node:fs:2539:36)
    at n$A (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7030)
    at xU9 (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7364)
    at L10._watchWithNodeFs (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:8774)
    at L10._handleFile (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:9500)
    at L10._addToNodeFs (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12508)
    at async file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276
    at async Promise.all (index 0)
Emitted 'error' event on R10 instance at:
    at R10._handleError (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:19822)
    at L10._addToNodeFs (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12605)
    at async file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276
    at async Promise.all (index 0) {
  errno: -24,
  syscall: 'watch',
  code: 'EMFILE',
  path: '.../.claude/settings.local.json',
  filename: '.../.claude/settings.local.json'
}

Workaround: remove .claude directory in the local project I am working with.
(Increasing the allowed number of files for operating system, e.g. 2x or more, did not help.)

kcosr · 1 year ago

I am facing this also. I do not know exactly when it started since I have been using another CLI for the past few weeks. I do all of my agentic development in docker (podman) containers and claude will not start. I've tried rebuilding the container. That's probably what triggered it in the first place (claude upgrade).

kcosr · 1 year ago

I am facing this also. I do not know exactly when it started since I have been using another CLI for the past few weeks. I do all of my agentic development in docker (podman) containers and claude will not start. I've tried rebuilding the container. That's probably what triggered it in the first place (claude upgrade).

This occurs as long as ~/.claude/settings.json exists, even if it is empty. Fortunately I do not use it so I can remove the file before starting claude.

🐳 sandboxuser@rocky-dev:/workspace$ cat ~/.claude/settings.json 
{}
🐳 sandboxuser@rocky-dev:/workspace$ claude
node:internal/fs/watchers:247
    const error = new UVException({
                  ^

Error: EMFILE: too many open files, watch '/home/sandboxuser/.claude/settings.json'
    at FSWatcher.<computed> (node:internal/fs/watchers:247:19)
    at watch (node:fs:2550:36)
    at uwA (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7030)
    at AE9 (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7364)
    at X00._watchWithNodeFs (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:8774)
    at X00._handleFile (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:9500)
    at X00._addToNodeFs (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12508)
    at async file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276
    at async Promise.all (index 0)
Emitted 'error' event on K00 instance at:
    at K00._handleError (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:19822)
    at X00._addToNodeFs (file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12605)
    at async file:///usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276
    at async Promise.all (index 0) {
  errno: -24,
  syscall: 'watch',
  code: 'EMFILE',
  path: '/home/sandboxuser/.claude/settings.json',
  filename: '/home/sandboxuser/.claude/settings.json'
}

Node.js v22.16.0
🐳 sandboxuser@rocky-dev:/workspace$ rm ~/.claude/settings.json
; this works
🐳 sandboxuser@rocky-dev:/workspace$ claude

huangmenglong · 11 months ago

@goxq Hello, I am currently experiencing this issue as well—an error within Docker. Do you have any other mitigation solutions? i need add hooks at PostUseTool Write|Edit

Win-commit · 11 months ago

It happened to me without any docker. I am using claude without adding settings of my own in a primitive way on Ubuntu 24.04.03. It is not new, happened several weeks ago once.它发生在我身上，没有任何泊坞工。我在 Ubuntu 24.04.03 上使用 claude，而无需以原始方式添加自己的设置。这并不新鲜，几周前发生过一次。 `` node:internal/fs/watchers:254 const error = new UVException({ ^ Error: EMFILE: too many open files, watch '.../.claude/settings.local.json' at FSWatcher.<computed> (node:internal/fs/watchers:254:19) at watch (node:fs:2539:36) at n$A (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7030) at xU9 (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:7364) at L10._watchWithNodeFs (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:8774) at L10._handleFile (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:9500) at L10._addToNodeFs (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12508) at async file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276 at async Promise.all (index 0) Emitted 'error' event on R10 instance at: at R10._handleError (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:19822) at L10._addToNodeFs (file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:12605) at async file://.../.nvm/versions/node/v24.8.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:784:17276 at async Promise.all (index 0) { errno: -24, syscall: 'watch', code: 'EMFILE', path: '.../.claude/settings.local.json', filename: '.../.claude/settings.local.json' } ` Workaround: remove .claude directory in the local project I am working with.解决方法：删除我正在使用的本地项目中的 .claude` 目录。 (Increasing the allowed number of files for operating system, e.g. 2x or more, did not help.)（增加作系统允许的文件数量，例如 2 倍或更多，没有帮助。

ye,it works well for me, too. Just remove /root/.claude folder, but it will drop the history

github-actions[bot] · 9 months ago

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

IuriiPurych · 9 months ago

Confirming on v2.1.2, non-Docker, Pop!_OS (Linux 6.17.4-76061704-generic), Node.js v22.21.1.

Both claude and claude update crash immediately with multiple ENOSPC errors:

Error: ENOSPC: System limit for number of file watchers reached, watch '/home/user/.claude'
    at FSWatcher.<computed> (node:internal/fs/watchers:254:19)
    at watch (node:fs:2549:36)
    ...
  errno: -28,
  syscall: 'watch',
  code: 'ENOSPC'

Watchers fail on: ~/.claude, ~/.claude/.credentials.json, ~/.claude/CLAUDE.md, ~/.claude/settings.json, ~/.claude/skills/, project .claude/settings.local.json, etc.

Welcome screen partially renders before crash — watchers seem to init late in startup.

Workaround: sudo sysctl fs.inotify.max_user_watches=524288

+1 for --no-config-watch / CLAUDE_DISABLE_CONFIG_WATCH=1.

github-actions[bot] · 8 months ago

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

marcindulak · 8 months ago

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

github-actions[bot] · 7 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.