【Claude Code】`error: An unknown error occurred, possibly due to low max file descriptors (Unexpected)` の対処法

エラーメッセージ

error: An unknown error occurred, possibly due to low max file descriptors (Unexpected)
Current limit: 256
To fix this, try running: ulimit -n 2147483646

または、以下のみ表示される場合もある。

error: An unknown error occurred (Unexpected)

環境

項目	バージョン
Claude Code	CLI 最新版 (2026年4月時点)
OS	macOS (Darwin 24.x)
シェル	zsh
ターミナル多重化	tmux

状況

tmux で複数ペインを開き、それぞれのペインで Claude Code を起動して並行作業していた。ある時点から新しいインスタンスが起動できなくなり、上記エラーが表示された。

原因

ターミナルや tmux から zsh を起動したとき、プロセスあたりのオープン可能ファイル数のソフト上限 (ulimit -n で表示) が 256 のままになっていることが多い（環境・接続元・ポリシーによっては異なる。ulimit -n とハード上限の ulimit -Hn で確認できる）。

Claude Code は内部でコードベースの読み込み・glob・grep などを行うため、1プロセスで多数のファイルを同時に開く。複数インスタンスを同時に起動すると、このソフト上限にすぐ到達し、新しいファイルを開けなくなってエラーが発生する。

解決方法

1. 現在のセッションで一時的に引き上げる

ulimit -n 10240

ulimit: open files: cannot modify limit のように失敗する場合は、ソフト上限がハード上限を超えられない。ulimit -Hn でハード上限を確認し、必要なら macOS のシステム側の上限 (launchctl limit maxfiles など) や管理者向けドキュメントを参照する。

この後、同じシェルから Claude Code を起動する。別のシェル／別ペインには反映されない。

2. zsh の対話セッション向けに毎回引き上げる

~/.zshrc に以下を追加する（ターミナルや tmux で対話的に zsh を起動したときに読み込まれる）。

ulimit -n 10240

追加後、シェルを再起動するか source ~/.zshrc を実行する。

source ~/.zshrc

設定が反映されたことを確認する。

ulimit -n
# => 10240

これにより、上記のとおり zsh が .zshrc を読むセッションではファイルディスクリプタのソフト上限が 10240 になり、Claude Code を複数起動しても上限に達しにくくなる。

試して失敗した方法: エラーメッセージ通りに ulimit -n 2147483646 を実行

エラーメッセージに表示される ulimit -n 2147483646 をそのまま実行しても、macOS ではカーネル側の上限を超えるため設定が反映されない場合がある。現実的な値 (10240 など) を指定するほうが確実。

補足: tmux 利用時の注意

ulimit で変わるのは**そのシェルプロセス（とそこから起動した子プロセス）**だけである。あるペインで上限を上げても、他の既存ペインには効かない。新しいペインは新しいシェルであり、親プロセス（tmux 経由）から初期のリソース制限を引き継いだうえで .zshrc などが実行される。そのため、各ペインで手動の ulimit に頼らず ~/.zshrc に書いておくと、新しいウィンドウ・ペインでも同じ前提で使いやすい。

参考

• Claude Code 公式ドキュメント
• getrlimit(2) - Manual Page (Apple Developer Archive) — ソフト／ハード上限の意味
• man zshbuiltins（ulimit の項。zsh の組み込みコマンド）
• man launchctl — システム全体の maxfiles など（必要に応じて）