windows-path-troubleshooting

Original：🇺🇸 English

Translated

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.

2installs

Sourcejosiahsiegel/claude-plugin-marketplace

Added on2026-02-04

NPX Install

npx skill4agent add josiahsiegel/claude-plugin-marketplace windows-path-troubleshooting

SKILL.md Content

View Translation Comparison →

🚨 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:

bash

# 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:

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

Issue 2: Git Bash MINGW Path Format

Symptom: Paths like

/s/repos/

/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:

Extract drive letter from first path segment (e.g.,
```
/s/
```
→
```
S
```
)
Add colon to drive letter (e.g.,
```
S
```
→
```
S:
```
)
Replace remaining forward slashes with backslashes
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:

bash

# 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:

Get the full Windows path from Git Bash:

bash

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

Convert to proper Windows path:
```
S:\repos\my-project
```

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

%USERPROFILE%

fail

Git Bash environment variables:

bash

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

Windows environment variables:

cmd

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

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:

Was the path provided by the user in MINGW format?
Does the path use forward slashes?
Is it a relative path?
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:

bash

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

🐛 Common Error Messages and Solutions

Error: "ENOENT: no such file or directory"

Most likely cause: Forward slashes instead of backslashes

Solution:

Check if path uses forward slashes
Convert to backslashes
Verify drive letter format
Retry operation

Error: "Invalid file path"

Most likely cause: MINGW path format

Solution:

Detect
```
/x/
```
pattern at start
Convert to
```
X:
```
format
Replace all forward slashes with backslashes
Retry operation

Error: "Access denied" or "Permission denied"

Most likely cause: Path is correct but permissions issue

Solution:

Verify file exists and is accessible
Check if file is locked by another process
Verify user has read/write permissions
Consider running Git Bash as administrator

Error: "File not found" but path looks correct

Possible causes:

Path has hidden characters (copy-paste issue)
File extension is hidden in Windows
Path has trailing spaces
Case sensitivity (some tools are case-sensitive)

Solution:

Ask user to run
```
ls -la
```
in Git Bash to verify exact filename
Check for file extensions
Trim whitespace from path
Match exact case of filename

📚 Platform-Specific Knowledge

Windows File System Characteristics

Path characteristics:

Drive letters: A-Z (typically C: for system, D-Z for additional drives)
Path separator: Backslash (
```
\
```
)
Case insensitive:
```
File.txt
```
same as
```
file.txt
```
Special characters: Avoid
```
< > : " | ? *
```
in filenames
Maximum path length: 260 characters (legacy limit, can be increased)

Git Bash on Windows

Git Bash is a POSIX-compatible environment:

Uses MINGW (Minimalist GNU for Windows)
Translates POSIX paths to Windows paths internally
Commands like
```
ls
```
,
```
pwd
```
,
```
cd
```
use POSIX format
Native Windows programs need Windows format paths

Key insight: Git Bash displays and accepts POSIX paths, but Windows APIs (used by Claude Code) require Windows paths.

WSL (Windows Subsystem for Linux)

WSL path mounting:

Windows drives mounted at
```
/mnt/c/
```
,
```
/mnt/d/
```
, etc.
WSL path:
```
/mnt/c/Users/name/project
```
Windows path:
```
C:\Users\name\project
```

Conversion:

Replace
```
/mnt/x/
```
with
```
X:
```
Replace forward slashes with backslashes

🎓 Teaching Users

When explaining path issues to users, use this template:

I encountered a path format issue. Here's what happened:

**The Problem:**
Claude Code's file tools (Edit, Write, Read) on Windows require paths in Windows
native format with backslashes (\), but Git Bash displays paths in POSIX format
with forward slashes (/).

**The Path Formats:**
- Git Bash shows: /s/repos/project/file.tsx
- Windows needs: S:\repos\project\file.tsx

**The Solution:**
I've converted your path to Windows format. For future reference, when working
with Claude Code on Windows with Git Bash:
1. Use backslashes (\) in file paths
2. Use drive letter format (C:, D:, S:) not MINGW format (/c/, /d/, /s/)
3. Run `pwd -W` in Git Bash to get Windows-formatted paths

**The Fix:**
✅ Now using: S:\repos\project\file.tsx

🔍 Advanced Scenarios

Scenario 1: Mixed Path Contexts

User is working with both WSL and Git Bash:

Ask which environment they're in
Use appropriate conversion
Document the choice

Scenario 2: Symbolic Links

Windows symbolic links:

mklink /D C:\link C:\target

Handling:

Follow the link to actual path
Use actual path in tool calls
Inform user if link resolution needed

Scenario 3: Docker Volumes

Docker volume mounts on Windows:

docker run -v C:\repos:/app

Path translation:

Outside container:
```
C:\repos\file.txt
```
Inside container:
```
/app/file.txt
```
Use context-appropriate format

✅ Success Criteria

You've successfully handled Windows paths when:

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

🆘 When to Use This Skill

PROACTIVELY apply this knowledge when:

User mentions they're on Windows
User mentions Git Bash or MINGW
You see paths starting with
```
/c/
```
,
```
/s/
```
, etc.
Edit/Write/Read tool fails with "file not found"
User provides paths with forward slashes on Windows
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.

windows-path-troubleshooting

NPX Install

Tags

SKILL.md Content

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

Documentation Guidelines

Windows Path Troubleshooting for Claude Code

🚨 CRITICAL: Always Use Backslashes on Windows for File Paths

The Rule

Why This Matters

🔍 Common Windows Path Issues in Claude Code

Issue 1: Forward Slashes in Tool Calls

Issue 2: Git Bash MINGW Path Format

Issue 3: Relative Paths in Git Bash

Issue 4: Environment Variable Expansion

Issue 5: Spaces in File Paths

Issue 6: UNC Network Paths

🔧 Path Detection and Conversion Algorithm

Step 1: Identify Path Format

Step 2: Conversion Process

🛠️ Interactive Path Fixing Workflow

Step 1: Detect the Error

Step 2: Analyze the Path

Step 3: Request Clarification (If Needed)

Step 4: Convert and Retry

Step 5: Verify Success

📋 Troubleshooting Checklist

🎯 Quick Reference: Path Conversion Examples

🚀 Best Practices for Windows File Operations

1. Always Convert Paths Proactively

2. Use pwd -W in Git Bash

3. Communicate Path Format Changes

4. Validate Before Tool Use

5. Handle User-Provided Paths Carefully

🐛 Common Error Messages and Solutions

Error: "ENOENT: no such file or directory"

Error: "Invalid file path"

Error: "Access denied" or "Permission denied"

Error: "File not found" but path looks correct

📚 Platform-Specific Knowledge

Windows File System Characteristics

Git Bash on Windows

WSL (Windows Subsystem for Linux)

🎓 Teaching Users

🔍 Advanced Scenarios

Scenario 1: Mixed Path Contexts

Scenario 2: Symbolic Links

Scenario 3: Docker Volumes

✅ Success Criteria

🆘 When to Use This Skill