Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix Startup crashes with misleading fd error when project has many session files

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Error Message

error: An unknown error occurred, possibly due to low max file descriptors (Unexpected)

Current limit: 256

To fix this, try running:

ulimit -n 2147483646

Fix Action

Workaround

Manually pruning old .jsonl files from ~/.claude/projects/<project>/ resolves the issue. A cron job with find ~/.claude/projects -name '*.jsonl' -mtime +30 -delete prevents recurrence.

Code Example

error: An unknown error occurred, possibly due to low max file descriptors (Unexpected)

Current limit: 256

To fix this, try running:

  ulimit -n 2147483646
RAW_BUFFERClick to expand / collapse

Bug description

Claude Code crashes on startup when a project has accumulated a large number of session history files (.jsonl) in ~/.claude/projects/<project>/. The error message incorrectly attributes the failure to low file descriptor limits.

Error message shown

error: An unknown error occurred, possibly due to low max file descriptors (Unexpected)

Current limit: 256

To fix this, try running:

  ulimit -n 2147483646

Actual cause

The file descriptor limit is not the problem. Claude Code reads all .jsonl session files in the project directory at startup. When a project accumulates enough sessions (~100+ files, ~100+ MB), the startup parser fails.

Reproduction

  1. Use Claude Code in a project over many sessions (we had 149 sessions, 135 MB total in .jsonl files)
  2. Attempt to launch claude in that project directory
  3. Startup crashes with the fd error above
  4. The suggested ulimit -n 2147483646 fix does not work (and exceeds the macOS kernel cap anyway)

Diagnostic proof

  • ulimit -n was already set to 1,048,576 — well above 256. The error message was wrong.
  • Launching Claude Code from a clean temp directory (/tmp/claude-test) worked fine.
  • Moving the 149 .jsonl files out of ~/.claude/projects/<project>/ immediately fixed the startup crash.
  • Three separate projects (145, 149, and 101 sessions) all had this issue.

Environment

  • macOS (Darwin 25.3.0)
  • Claude Code installed via npm global (~/.npm-global/bin/claude)
  • Node.js v22.14.0

Expected behavior

  1. Startup should not choke on session history. Either lazy-load sessions, cap what's read at startup, or implement built-in session retention/pruning.
  2. There should be a built-in config option for session retention (e.g., maxSessionAge, maxSessionCount).
  3. The error message should be accurate. If the failure is an OOM or parse timeout from large session state, say that — not "low max file descriptors."

Workaround

Manually pruning old .jsonl files from ~/.claude/projects/<project>/ resolves the issue. A cron job with find ~/.claude/projects -name '*.jsonl' -mtime +30 -delete prevents recurrence.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

  1. Startup should not choke on session history. Either lazy-load sessions, cap what's read at startup, or implement built-in session retention/pruning.
  2. There should be a built-in config option for session retention (e.g., maxSessionAge, maxSessionCount).
  3. The error message should be accurate. If the failure is an OOM or parse timeout from large session state, say that — not "low max file descriptors."

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix Startup crashes with misleading fd error when project has many session files