windows-path-troubleshooting

name

windows-path-troubleshooting

description

Complete Windows file path troubleshooting knowledge for Claude Code on Git Bash and Windows environments. PROACTIVELY activate for: (1) file path errors on Windows, (2) backslash vs forward slash issues, (3) Edit/Write/Read tool failures, (4) MINGW path resolution, (5) cross-platform path conversion, (6) MSYS_NO_PATHCONV usage, (7) double-slash escape patterns (//c/foo), (8) UNC and long path limits, (9) WSL vs native Windows interop. Provides: path-conversion rules, troubleshooting flowchart, MSYS env-var recipes, double-slash escape patterns, and Windows file-operation best practices.

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Windows Path Troubleshooting for Claude Code

🚨 CRITICAL: Always Use Backslashes on Windows for File Paths

MANDATORY: When using Edit, Write, or Read tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

The Rule

Windows File Path Requirements:

• ✅ CORRECT: D:\repos\project\file.tsx
• ❌ WRONG: D:/repos/project/file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• Read tool file_path parameter
• All file operations on Windows systems

Why This Matters

Common error message when using forward slashes on Windows:

Error: ENOENT: no such file or directory

Root cause:

• Windows native file system uses backslashes (\) as path separators
• Forward slashes (/) work in some Windows contexts but NOT in Claude Code file tools
• Git Bash displays paths with forward slashes but Windows APIs require backslashes
• Claude Code's Read/Write/Edit tools use Windows native APIs that expect backslashes

🔍 Common Windows Path Issues in Claude Code

Issue 1: Forward Slashes in Tool Calls

Symptom:

Edit tool fails with "file not found" or "no such file or directory"

Cause: Using forward slashes copied from Git Bash output:

# Git Bash shows:
/s/repos/claude-plugin-marketplace/file.tsx

Incorrect usage:

Edit(file_path="/s/repos/myproject/file.tsx")

Correct usage:

Edit(file_path="S:\repos\myproject\file.tsx")

Solution steps:

1. Identify the Windows drive letter (e.g., /s/ → S:)
2. Replace forward slashes with backslashes
3. Add drive letter with colon
4. Use absolute Windows path format

Issue 2: Git Bash MINGW Path Format

Symptom: Paths like /s/repos/ or /c/Users/ don't work in Edit/Write/Read tools

MINGW path format explained:

• Git Bash uses POSIX-style paths on Windows
• Drive letters are represented as /c/, /d/, /s/, etc.
• These are MINGW virtual paths, not Windows paths
• Claude Code tools need Windows-native paths

Conversion table:

Git Bash (MINGW)	Windows Native
/c/Users/name/	C:\Users\name\
/d/repos/project/	D:\repos\project\
/s/work/code/	S:\work\code\
/mnt/c/Windows/	C:\Windows\

Conversion algorithm:

1. Extract drive letter from first path segment (e.g., /s/ → S)
2. Add colon to drive letter (e.g., S → S:)
3. Replace remaining forward slashes with backslashes
4. Combine: S: + \repos\project\file.tsx

Issue 3: Relative Paths in Git Bash

Symptom: Relative paths from Git Bash don't resolve correctly in Claude Code tools

Cause: Git Bash current working directory uses MINGW format, but Claude Code tools use Windows format

Example scenario:

# In Git Bash:
pwd
# Shows: /s/repos/my-project

# User provides relative path:
./src/components/Button.tsx

Problem: Claude Code can't resolve ./src/ from MINGW /s/repos/my-project

Solution:

1. Get the full Windows path from Git Bash:

   pwd -W
   # Shows: S:/repos/my-project (Windows format with forward slashes)
   

2. Convert to proper Windows path: S:\repos\my-project
3. Append relative path with backslashes: S:\repos\my-project\src\components\Button.tsx

Issue 4: Environment Variable Expansion

Symptom: Paths with environment variables like $HOME or %USERPROFILE% fail

Git Bash environment variables:

echo $HOME
# Shows: /c/Users/username (MINGW format)

Windows environment variables:

echo %USERPROFILE%
# Shows: C:\Users\username (Windows format)

Best practice:

• Avoid environment variables in file paths for Claude Code tools
• Use absolute Windows paths instead
• If user provides $HOME, ask them to run echo $HOME and convert the result

Issue 5: Spaces in File Paths

Symptom: Paths with spaces break or cause "file not found" errors

Correct handling:

✅ CORRECT: Edit(file_path="C:\Program Files\My App\config.json")
✅ CORRECT: Edit(file_path="D:\My Documents\project\file.txt")

Notes:

• Do NOT add quotes around the path in the parameter
• The tool call itself handles escaping
• Spaces are fine in Windows paths when using backslashes

Issue 6: UNC Network Paths

Symptom: Network paths like \\server\share\file.txt fail

Windows UNC format:

\\server\share\folder\file.txt

Git Bash representation:

//server/share/folder/file.txt

Correct usage in Claude Code:

Edit(file_path="\\\\server\\share\\folder\\file.txt")

Note: Backslashes must be doubled in some contexts due to escaping, but Claude Code tools handle this automatically.

🔧 Path Detection and Conversion Algorithm

When a user provides a file path, follow this decision tree:

Step 1: Identify Path Format

MINGW Path (Git Bash):

• Starts with / followed by single letter and / (e.g., /c/, /s/)
• Example: /s/repos/project/file.tsx
• Action: Convert to Windows format

Windows Path:

• Starts with drive letter and colon (e.g., C:, D:)
• Uses backslashes or forward slashes
• Example: S:\repos\project\file.tsx or S:/repos/project/file.tsx
• Action: Ensure backslashes are used

Relative Path:

• Starts with ./ or ../ or just filename
• Example: ./src/components/Button.tsx
• Action: Request full path from user or detect current directory

UNC Path:

• Starts with \\ or //
• Example: \\server\share\file.txt
• Action: Ensure backslashes are used

Step 2: Conversion Process

For MINGW paths (/x/...):

Input: /s/repos/myproject/src/components/Button.tsx

Process:
1. Extract drive letter: "s"
2. Uppercase: "S"
3. Add colon: "S:"
4. Replace remaining slashes: \repos\myproject\src\components\Button.tsx
5. Combine: S:\repos\myproject\src\components\Button.tsx

Output: S:\repos\myproject\src\components\Button.tsx

For Windows paths with forward slashes (X:/...):

Input: S:/repos/project/file.tsx

Process:
1. Detect drive letter already present: "S:"
2. Replace forward slashes with backslashes: \repos\project\file.tsx
3. Combine: S:\repos\project\file.tsx

Output: S:\repos\project\file.tsx

For relative paths:

Input: ./src/components/Button.tsx
Current directory (from user or detection): S:\repos\my-project

Process:
1. Remove ./ prefix
2. Replace forward slashes: src\components\Button.tsx
3. Combine with current directory: S:\repos\my-project\src\components\Button.tsx

Output: S:\repos\my-project\src\components\Button.tsx

🛠️ Interactive Path Fixing Workflow

When you encounter a file path error on Windows:

Step 1: Detect the Error

Error indicators:

• "ENOENT: no such file or directory"
• "file not found"
• Edit/Write/Read tool failure
• User mentions "Windows" or "Git Bash"

Step 2: Analyze the Path

Ask yourself:

1. Was the path provided by the user in MINGW format?
2. Does the path use forward slashes?
3. Is it a relative path?
4. Did I receive the path from a Git Bash command output?

Step 3: Request Clarification (If Needed)

If the path is ambiguous, ask:

I see you're working on Windows with Git Bash. To ensure I use the correct path format,
could you run this command and share the output?

pwd -W

This will give me the Windows-formatted path.

Step 4: Convert and Retry

Conversion template:

I'll convert the path from Git Bash format to Windows format:
- Git Bash: /s/repos/project/file.tsx
- Windows: S:\repos\project\file.tsx

Retrying with the correct Windows path...

Step 5: Verify Success

After conversion, verify the operation succeeded and explain what was fixed:

✅ Successfully edited the file using the Windows path format (S:\repos\...).

Note: On Windows with Git Bash, always use backslashes (\) in file paths for
Claude Code's Edit/Write/Read tools, even though Git Bash displays paths with
forward slashes (/).

📋 Troubleshooting Checklist

When file operations fail on Windows:

• Check path separator: Are backslashes (\) used instead of forward slashes (/)?
• Check drive letter format: Is it C: not /c/?
• Check MINGW conversion: Did you convert /x/path to X:\path?
• Check relative vs absolute: Is the path absolute starting with drive letter?
• Check environment variables: Did you expand $HOME or %USERPROFILE%?
• Check spaces: Are spaces in the path handled correctly?
• Check UNC paths: Are network paths using \\server\share format?
• Check file existence: Does the file actually exist at that path?

🎯 Quick Reference: Path Conversion Examples

Context	Path Format	Claude Code Tool Format
Git Bash pwd	/s/repos/project	S:\repos\project
Git Bash relative	./src/file.tsx	S:\repos\project\src\file.tsx
Windows Explorer	S:\repos\project\file.tsx	S:\repos\project\file.tsx ✅
Windows with /	S:/repos/project/file.tsx	S:\repos\project\file.tsx
MINGW full path	/c/Users/name/file.txt	C:\Users\name\file.txt
Network share (Git Bash)	//server/share/file.txt	\\server\share\file.txt
WSL path	/mnt/c/repos/project	C:\repos\project

🚀 Best Practices for Windows File Operations

1. Always Convert Paths Proactively

Don't wait for errors - If you see a path that looks like MINGW format, convert it immediately:

User provides: /s/repos/project/file.tsx
You think: "This is MINGW format, I need to convert it to S:\repos\project\file.tsx"
You do: Convert before calling Edit/Write/Read tool

2. Use pwd -W in Git Bash

When you need current directory on Windows:

# Instead of:
pwd                    # Shows: /s/repos/project (MINGW format)

# Use:
pwd -W                 # Shows: S:/repos/project (Windows format with /)

Then convert the forward slashes to backslashes.

3. Communicate Path Format Changes

Always explain when you convert paths:

I'll convert the Git Bash path to Windows format for the Edit tool:
- From: /s/repos/project/file.tsx
- To: S:\repos\project\file.tsx

This helps users understand the requirement and learn for future interactions.

4. Validate Before Tool Use

Before calling Edit/Write/Read tools on Windows:

Pre-flight checklist:
✅ Path starts with drive letter and colon (e.g., C:, S:)
✅ Path uses backslashes (\) not forward slashes (/)
✅ Path is absolute, not relative
✅ No MINGW format (no /c/, /s/, etc.)

5. Handle User-Provided Paths Carefully

User might provide paths in various formats:

• Copy-pasted from Git Bash (MINGW format)
• Copy-pasted from Windows Explorer (Windows format)
• Typed manually (could be either)
• From command output (varies by tool)

Always detect and convert as needed.

Error Lookup, Platform Notes, User Teaching & Advanced Scenarios

Detailed lookup tables for common Claude Code Windows path errors, platform-specific behavior (PowerShell, CMD, Git Bash, WSL, Node/Python), user-teaching scripts, and advanced path scenarios (UNC paths, long paths, spaces, special characters) live in references/error-platform-advanced.md. Load that reference when the quick conversion workflow does not explain a path failure.

✅ Success Criteria

You've successfully handled Windows paths when:

1. ✅ All Edit/Write/Read tool calls use backslashes on Windows
2. ✅ MINGW paths are converted before tool use
3. ✅ Relative paths are resolved to absolute Windows paths
4. ✅ User understands why conversion was necessary
5. ✅ File operations succeed without path-related errors
6. ✅ Path format is consistent throughout the session

🆘 When to Use This Skill

PROACTIVELY apply this knowledge when:

1. User mentions they're on Windows
2. User mentions Git Bash or MINGW
3. You see paths starting with /c/, /s/, etc.
4. Edit/Write/Read tool fails with "file not found"
5. User provides paths with forward slashes on Windows
6. You need to read/edit/write files on Windows system

This skill is CRITICAL for Windows users - Path format errors are the #1 cause of file operation failures on Windows with Git Bash.