Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix Session hangs on startup when additionalDirectories contains unreachable network drive path (Windows) [1 comments, 2 participants]

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…
GitHub stats
anthropics/claude-code#48361•Fetched 2026-04-16 07:02:23
View on GitHub
Comments
1
Participants
2
Timeline
7
Reactions
0
Author
rschuetze1rschuetze1
Participants
github-actions[bot]github-actions[bot]rschuetze1rschuetze1
Timeline (top)
labeled ×4closed ×1commented ×1cross-referenced ×1

Error Message

Session startup blocks completely. No error message is shown. After 60 seconds, a handshake timeout occurs (in VS Code extension) or the CLI just hangs.

Root Cause

Root Cause Investigation

Fix Action

Workaround

I wrote a SessionStart hook that warns about unreachable paths at session start. However, this only warns after startup — it cannot prevent the hang since the directory scanning happens before hooks run.

The real fix needs to be in Claude Code's startup sequence: additionalDirectories scanning should have a timeout or use non-blocking I/O.

RAW_BUFFERClick to expand / collapse

Bug Description

When ~/.claude/settings.json contains an additionalDirectories entry pointing to a network drive that is not currently mounted (e.g., Z:\scripts when the NAS is offline), Claude Code hangs indefinitely during session startup, resulting in a 60-second handshake timeout.

Steps to Reproduce

  1. Mount a network drive (e.g., Z: → NAS share)
  2. In a Claude Code session, approve access to a path on that drive (e.g., Z:\scripts)
  3. This adds Z:\scripts to permissions.additionalDirectories in ~/.claude/settings.json
  4. Disconnect from the network / unmount the drive
  5. Try to start a new Claude Code session → hangs indefinitely

Expected Behavior

Claude Code should either:

  • Skip unreachable directories with a warning instead of hanging
  • Use a timeout when scanning additionalDirectories paths
  • Not block session startup on directory enumeration

Actual Behavior

Session startup blocks completely. No error message is shown. After 60 seconds, a handshake timeout occurs (in VS Code extension) or the CLI just hangs.

Root Cause Investigation

Through binary search on the settings.json entries, I isolated the exact blocker: a single additionalDirectories entry pointing to an unmounted network drive (Z:\scripts). Removing just that one entry immediately fixed the startup.

This is a common scenario for users who work from different locations (e.g., home with NAS vs. mobile/train without NAS).

The 803 permission rules and 13 hooks in the same settings.json were NOT the problem — all were restored successfully after removing the unreachable path.

Environment

  • OS: Windows 11 Pro 10.0.26200
  • Claude Code: 2.1.109 (VS Code Extension + CLI)
  • Shell: Git Bash

Related Issues

  • #46647 (Handshake timeout — same symptom, possibly same root cause for some users)
  • #29935 (UNC paths in settings.json)
  • #24140 (Symlinked .claude on network drive)

Workaround

I wrote a SessionStart hook that warns about unreachable paths at session start. However, this only warns after startup — it cannot prevent the hang since the directory scanning happens before hooks run.

The real fix needs to be in Claude Code's startup sequence: additionalDirectories scanning should have a timeout or use non-blocking I/O.

extent analysis

TL;DR

Implement a timeout or non-blocking I/O for scanning additionalDirectories in Claude Code's startup sequence to prevent hangs when encountering unreachable network drives.

Guidance

  • Verify that the issue is indeed caused by an unreachable network drive by checking the ~/.claude/settings.json file for additionalDirectories entries pointing to unmounted drives.
  • Consider implementing a hook like the SessionStart hook mentioned, but focus on detecting and handling unreachable paths before the directory scanning phase.
  • To mitigate the issue, users can manually remove or comment out unreachable additionalDirectories entries in their ~/.claude/settings.json file before starting a new Claude Code session.
  • Investigate the possibility of using asynchronous or non-blocking I/O operations when scanning additionalDirectories to prevent blocking the startup process.

Example

No specific code example is provided due to the lack of details about the internal implementation of Claude Code's startup sequence. However, the concept would involve modifying the directory scanning logic to either timeout after a certain period or to use non-blocking I/O to avoid hanging.

Notes

The exact implementation details of the fix depend on the internal architecture of Claude Code, which is not fully disclosed in the issue. The provided guidance is based on the information given and aims to point towards a potential solution.

Recommendation

Apply a workaround by manually managing additionalDirectories entries in ~/.claude/settings.json to avoid pointing to unreachable network drives until a proper fix is implemented in Claude Code. This is because the root cause is identified but requires changes to the application's startup sequence, which may not be immediately feasible for all users.

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…
#dependency conflict#environment setup#docker error#permission error#memory optimization

Still need to ship something?

×6

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

Back to top recommendations

TRENDING