windows-path-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🚨 CRITICAL GUIDELINES

🚨 关键指南

Windows File Path Requirements

Windows文件路径要求

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

强制要求：在Windows系统下使用文件路径时始终使用反斜杠

在Windows系统下使用Edit或Write工具时，必须在文件路径中使用反斜杠（

），而非正斜杠（

）。

示例：

❌ 错误格式：
```
D:/repos/project/file.tsx
```
✅ 正确格式：
```
D:\repos\project\file.tsx
```

此要求适用于：

Edit工具的file_path参数
Write工具的file_path参数
Windows系统上的所有文件操作

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

除非用户明确要求，否则切勿创建新的文档文件。

优先级：优先更新现有README.md文件，而非创建新文档
仓库整洁性：保持仓库根目录整洁 - 除非用户要求，否则仅保留README.md
风格：文档应简洁、直接、专业 - 避免AI生成式语气
用户偏好：仅在用户明确要求文档时才创建额外的.md文件

Windows Path Troubleshooting for Claude Code

适用于Claude Code的Windows路径排障指南

🚨 CRITICAL: Always Use Backslashes on Windows for File Paths

🚨 关键要求：在Windows系统下使用文件路径时始终使用反斜杠

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

强制要求：在Windows系统下使用Edit、Write或Read工具时，必须在文件路径中使用反斜杠（
\
），而非正斜杠（
/
）。

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

Windows文件路径要求：

✅ 正确格式：
```
D:\repos\project\file.tsx
```
❌ 错误格式：
```
D:/repos/project/file.tsx
```

此要求适用于：

Edit工具的
```
file_path
```
参数
Write工具的
```
file_path
```
参数
Read工具的
```
file_path
```
参数
Windows系统上的所有文件操作

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

在Windows系统下使用正斜杠时常见的错误信息：

Error: ENOENT: no such file or directory

根本原因：

Windows原生文件系统使用反斜杠（
```
\
```
）作为路径分隔符
正斜杠（
```
/
```
）在部分Windows场景中可用，但在Claude Code的文件工具中不可用
Git Bash使用正斜杠显示路径，但Windows API要求使用反斜杠
Claude Code的Read/Write/Edit工具使用Windows原生API，该API期望路径使用反斜杠

🔍 Common Windows Path Issues in Claude Code

🔍 Claude Code中常见的Windows路径问题

Issue 1: Forward Slashes in Tool Calls

问题1：工具调用中使用正斜杠

Symptom:

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

Cause: Using forward slashes copied from Git Bash output:

bash

undefined

症状：

Edit工具执行失败，提示"file not found"或"no such file or directory"

原因： 使用从Git Bash输出中复制的正斜杠路径：

bash

undefined

Git Bash shows:

Git Bash显示：

/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

/s/repos/claude-plugin-marketplace/file.tsx


**错误用法：**

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


**正确用法：**

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


**解决步骤：**
1. 确定Windows驱动器号（例如：`/s/` → `S:`）
2. 将正斜杠替换为反斜杠
3. 添加带冒号的驱动器号
4. 使用绝对Windows路径格式

Issue 2: Git Bash MINGW Path Format

问题2：Git Bash MINGW路径格式

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
```

症状： 类似

/s/repos/

或

/c/Users/

的路径在Edit/Write/Read工具中无法使用

MINGW路径格式说明：

Git Bash在Windows系统上使用POSIX风格的路径
驱动器号表示为
```
/c/
```
、
```
/d/
```
、
```
/s/
```
等
这些是MINGW虚拟路径，而非Windows路径
Claude Code工具需要Windows原生路径

转换对照表：

Git Bash (MINGW)	Windows原生路径
`/c/Users/name/`	`C:\Users\name\`
`/d/repos/project/`	`D:\repos\project\`
`/s/work/code/`	`S:\work\code\`
`/mnt/c/Windows/`	`C:\Windows\`

转换算法：

从第一个路径段中提取驱动器号（例如：
```
/s/
```
→
```
S
```
）
为驱动器号添加冒号（例如：
```
S
```
→
```
S:
```
）
将剩余的正斜杠替换为反斜杠
组合路径：
```
S:
```
+
```
\repos\project\file.tsx
```

Issue 3: Relative Paths in Git Bash

问题3：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

undefined

症状： 从Git Bash获取的相对路径在Claude Code工具中无法正确解析

原因： Git Bash当前工作目录使用MINGW格式，但Claude Code工具使用Windows格式

示例场景：

bash

undefined

In Git Bash:

在Git Bash中：

pwd

Shows: /s/repos/my-project

显示：/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:
   ```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

./src/components/Button.tsx


**问题：**
Claude Code无法从MINGW路径`/s/repos/my-project`解析`./src/`

**解决方案：**
1. 从Git Bash获取完整Windows路径：
   ```bash
   pwd -W
   # 显示：S:/repos/my-project（带正斜杠的Windows格式）

转换为标准Windows路径：
```
S:\repos\my-project
```

附加带反斜杠的相对路径：

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

Issue 4: Environment Variable Expansion

问题4：环境变量展开

Symptom: Paths with environment variables like

$HOME

%USERPROFILE%

fail

Git Bash environment variables:

bash

echo $HOME

症状： 包含

$HOME

或

%USERPROFILE%

等环境变量的路径执行失败

Git Bash环境变量：

bash

echo $HOME

Shows: /c/Users/username (MINGW format)

显示：/c/Users/username（MINGW格式）


**Windows environment variables:**
```cmd
echo %USERPROFILE%


**Windows环境变量：**
```cmd
echo %USERPROFILE%

Shows: C:\Users\username (Windows format)

显示：C:\Users\username（Windows格式）


**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


**最佳实践：**
- 在Claude Code工具的文件路径中避免使用环境变量
- 改用绝对Windows路径
- 如果用户提供`$HOME`，请让他们运行`echo $HOME`并转换结果

Issue 5: Spaces in File Paths

问题5：文件路径中的空格

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

症状： 包含空格的路径执行失败或提示"file not found"错误

正确处理方式：

✅ 正确格式：Edit(file_path="C:\Program Files\My App\config.json")
✅ 正确格式：Edit(file_path="D:\My Documents\project\file.txt")

注意事项：

请勿在参数中的路径两端添加引号
工具调用会自动处理转义
使用反斜杠时，Windows路径中的空格是合法的

Issue 6: UNC Network Paths

问题6：UNC网络路径

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.

症状： 类似

\\server\share\file.txt

的网络路径执行失败

Windows UNC格式：

\\server\share\folder\file.txt

Git Bash表示方式：

//server/share/folder/file.txt

Claude Code中的正确用法：

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

注意： 在某些场景中，反斜杠必须加倍以实现转义，但Claude Code工具会自动处理此问题。

🔧 Path Detection and Conversion Algorithm

🔧 路径检测与转换算法

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

当用户提供文件路径时，请遵循以下决策树：

Step 1: Identify Path Format

步骤1：识别路径格式

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

MINGW路径（Git Bash）：

以
```
/
```
开头，后跟单个字母和
```
/
```
（例如：
```
/c/
```
、
```
/s/
```
）
示例：
```
/s/repos/project/file.tsx
```
操作： 转换为Windows格式

Windows路径：

以驱动器号和冒号开头（例如：
```
C:
```
、
```
D:
```
）
使用反斜杠或正斜杠

示例：

S:\repos\project\file.tsx

或

S:/repos/project/file.tsx

操作： 确保使用反斜杠

相对路径：

以
```
./
```
、
```
../
```
或文件名开头
示例：
```
./src/components/Button.tsx
```
操作： 请求用户提供完整路径或检测当前目录

UNC路径：

以
```
\\
```
或
```
//
```
开头
示例：
```
\\server\share\file.txt
```
操作： 确保使用反斜杠

Step 2: Conversion Process

步骤2：转换流程

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

针对MINGW路径（
/x/...
）：

输入：/s/repos/myproject/src/components/Button.tsx

处理流程：
1. 提取驱动器号："s"
2. 转换为大写："S"
3. 添加冒号："S:"
4. 替换剩余斜杠：\repos\myproject\src\components\Button.tsx
5. 组合路径：S:\repos\myproject\src\components\Button.tsx

输出：S:\repos\myproject\src\components\Button.tsx

针对带正斜杠的Windows路径（
X:/...
）：

输入：S:/repos/project/file.tsx

处理流程：
1. 检测到已存在驱动器号："S:"
2. 将正斜杠替换为反斜杠：\repos\project\file.tsx
3. 组合路径：S:\repos\project\file.tsx

输出：S:\repos\project\file.tsx

针对相对路径：

输入：./src/components/Button.tsx
当前目录（来自用户或检测结果）：S:\repos\my-project

处理流程：
1. 移除./前缀
2. 将正斜杠替换为反斜杠：src\components\Button.tsx
3. 与当前目录组合：S:\repos\my-project\src\components\Button.tsx

输出：S:\repos\my-project\src\components\Button.tsx

🛠️ Interactive Path Fixing Workflow

🛠️ 交互式路径修复流程

When you encounter a file path error on Windows:

当在Windows系统下遇到文件路径错误时：

Step 1: Detect the Error

步骤1：检测错误

Error indicators:

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

错误指标：

"ENOENT: no such file or directory"
"file not found"
Edit/Write/Read工具执行失败
用户提及"Windows"或"Git Bash"

Step 2: Analyze the Path

步骤2：分析路径

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?

自问：

用户提供的路径是否为MINGW格式？
路径是否使用正斜杠？
是否为相对路径？
路径是否来自Git Bash命令输出？

Step 3: Request Clarification (If Needed)

步骤3：请求澄清（如有需要）

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.

如果路径不明确，请询问：

我了解您正在Windows系统下使用Git Bash。为确保我使用正确的路径格式，
能否运行以下命令并分享输出结果？

pwd -W

该命令将为我提供Windows格式的路径。

Step 4: Convert and Retry

步骤4：转换并重试

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

转换模板：

我将把路径从Git Bash格式转换为Windows格式：
- Git Bash：/s/repos/project/file.tsx
- Windows：S:\repos\project\file.tsx

正在使用正确的Windows路径重试操作...

Step 5: Verify Success

步骤5：验证成功

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 (/).

转换完成后，验证操作是否成功，并解释修复内容：

✅ 已使用Windows路径格式（S:\repos\...）成功编辑文件。

注意：在Windows系统下使用Git Bash时，Claude Code的Edit/Write/Read工具始终要求使用反斜杠（\）作为文件路径分隔符，即使Git Bash使用正斜杠（/）显示路径。

📋 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?

当Windows系统下的文件操作失败时：

检查路径分隔符：是否使用反斜杠（
```
\
```
）而非正斜杠（
```
/
```
）？
检查驱动器号格式：是否为
```
C:
```
而非
```
/c/
```
？
检查MINGW转换：是否已将
```
/x/path
```
转换为
```
X:\path
```
？
检查相对路径与绝对路径：路径是否为以驱动器号开头的绝对路径？
检查环境变量：是否已展开
```
$HOME
```
或
```
%USERPROFILE%
```
？
检查空格：路径中的空格是否已正确处理？
检查UNC路径：网络路径是否使用
```
\\server\share
```
格式？
检查文件存在性：该路径下是否确实存在文件？

🎯 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`

场景	路径格式	Claude Code工具格式
Git Bash pwd	`/s/repos/project`	`S:\repos\project`
Git Bash相对路径	`./src/file.tsx`	`S:\repos\project\src\file.tsx`
Windows资源管理器	`S:\repos\project\file.tsx`	`S:\repos\project\file.tsx` ✅
Windows带正斜杠	`S:/repos/project/file.tsx`	`S:\repos\project\file.tsx`
MINGW完整路径	`/c/Users/name/file.txt`	`C:\Users\name\file.txt`
网络共享（Git Bash）	`//server/share/file.txt`	`\\server\share\file.txt`
WSL路径	`/mnt/c/repos/project`	`C:\repos\project`

🚀 Best Practices for Windows File Operations

🚀 Windows文件操作最佳实践

1. Always Convert Paths Proactively

1. 主动转换路径

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

不要等待错误发生 - 如果发现路径为MINGW格式，请立即转换：

用户提供：/s/repos/project/file.tsx
您的思考："这是MINGW格式，我需要将其转换为S:\repos\project\file.tsx"
您的操作：在调用Edit/Write/Read工具前完成转换

2. Use pwd -W in Git Bash

2. 在Git Bash中使用pwd -W

When you need current directory on Windows:

bash

undefined

当您需要Windows系统下的当前目录时：

bash

undefined

Instead of:

不要使用：

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

pwd # 显示：/s/repos/project（MINGW格式）

Use:

请使用：

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


Then convert the forward slashes to backslashes.

pwd -W # 显示：S:/repos/project（带正斜杠的Windows格式）


然后将正斜杠转换为反斜杠。

3. Communicate Path Format Changes

3. 告知用户路径格式变更

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.

转换路径时始终向用户说明：

我将把Git Bash路径转换为Windows格式以用于Edit工具：
- 原路径：/s/repos/project/file.tsx
- 转换后：S:\repos\project\file.tsx

这有助于用户理解要求并在未来交互中学习正确用法。

4. Validate Before Tool Use

4. 工具使用前验证

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

在Windows系统下调用Edit/Write/Read工具前：

预检查清单：
✅ 路径以驱动器号和冒号开头（例如：C:, S:）
✅ 路径使用反斜杠（\）而非正斜杠（/）
✅ 路径为绝对路径
✅ 非MINGW格式（无/c/、/s/等）

5. Handle User-Provided Paths Carefully

5. 谨慎处理用户提供的路径

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.

用户可能以多种格式提供路径：

从Git Bash复制（MINGW格式）
从Windows资源管理器复制（Windows格式）
手动输入（可能为任意格式）
来自命令输出（格式因工具而异）

始终检测并按需转换。

🐛 Common Error Messages and Solutions

🐛 常见错误信息与解决方案

Error: "ENOENT: no such file or directory"

错误："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"

错误："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

最可能原因： MINGW路径格式

解决方案：

检测路径开头是否为
```
/x/
```
模式
转换为
```
X:
```
格式
将所有正斜杠替换为反斜杠
重试操作

Error: "Access denied" or "Permission denied"

错误："Access denied"或"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

最可能原因： 路径正确但权限问题

解决方案：

验证文件是否存在且可访问
检查文件是否被其他进程锁定
验证用户是否具备读写权限
考虑以管理员身份运行Git Bash

Error: "File not found" but path looks correct

错误："File not found"但路径看似正确

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

可能原因：

路径包含隐藏字符（复制粘贴问题）
Windows系统中文件扩展名被隐藏
路径包含尾随空格
大小写敏感（部分工具区分大小写）

解决方案：

请用户在Git Bash中运行
```
ls -la
```
以验证确切文件名
检查文件扩展名
移除路径中的空格
匹配文件名的确切大小写

📚 Platform-Specific Knowledge

📚 平台特定知识

Windows File System Characteristics

Windows文件系统特性

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)

路径特性：

驱动器号：A-Z（通常C:为系统盘，D-Z为附加驱动器）
路径分隔符：反斜杠（
```
\
```
）
大小写不敏感：
```
File.txt
```
与
```
file.txt
```
相同
特殊字符：文件名中避免使用
```
< > : " | ? *
```
最大路径长度：260个字符（旧版限制，可扩展）

Git Bash on Windows

Windows系统下的Git Bash

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.

Git Bash是POSIX兼容环境：

使用MINGW（Minimalist GNU for Windows）
在内部将POSIX路径转换为Windows路径
```
ls
```
、
```
pwd
```
、
```
cd
```
等命令使用POSIX格式
原生Windows程序需要Windows格式路径

关键要点： Git Bash显示并接受POSIX路径，但Claude Code使用的Windows API要求使用Windows路径。

WSL (Windows Subsystem for Linux)

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

WSL路径挂载：

Windows驱动器挂载在
```
/mnt/c/
```
、
```
/mnt/d/
```
等位置
WSL路径：
```
/mnt/c/Users/name/project
```
Windows路径：
```
C:\Users\name\project
```

转换方法：

将
```
/mnt/x/
```
替换为
```
X:
```
将正斜杠替换为反斜杠

🎓 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

向用户解释路径问题时，请使用以下模板：

我遇到了路径格式问题。详情如下：

**问题：**
Windows系统下Claude Code的文件工具（Edit、Write、Read）要求使用带反斜杠（\）的Windows原生路径，但Git Bash使用带正斜杠（/）的POSIX格式显示路径。

**路径格式对比：**
- Git Bash显示：/s/repos/project/file.tsx
- Windows需要：S:\repos\project\file.tsx

**解决方案：**
我已将您的路径转换为Windows格式。未来在Windows系统下使用Git Bash与Claude Code交互时，请遵循以下规则：
1. 文件路径中使用反斜杠（\）
2. 使用驱动器号格式（C:、D:、S:）而非MINGW格式（/c/、/d/、/s/）
3. 在Git Bash中运行`pwd -W`以获取Windows格式路径

**修复结果：**
✅ 现在使用的路径：S:\repos\project\file.tsx

🔍 Advanced Scenarios

🔍 高级场景

Scenario 1: Mixed Path Contexts

场景1：混合路径上下文

User is working with both WSL and Git Bash:

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

用户同时使用WSL和Git Bash：

询问用户当前所处环境
使用相应的转换方法
记录选择的转换方式

Scenario 2: Symbolic Links

场景2：符号链接

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

Windows符号链接：

mklink /D C:\link C:\target

处理方式：

跟踪链接至实际路径
在工具调用中使用实际路径
如果需要解析链接，请告知用户

Scenario 3: Docker Volumes

场景3：Docker卷

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

Windows系统下的Docker卷挂载：

docker run -v C:\repos:/app

路径转换：

容器外部：
```
C:\repos\file.txt
```
容器内部：
```
/app/file.txt
```
使用适合当前上下文的格式

✅ 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

当您满足以下条件时，即已成功处理Windows路径问题：

✅ Windows系统下所有Edit/Write/Read工具调用均使用反斜杠
✅ MINGW路径在工具调用前已完成转换
✅ 相对路径已解析为绝对Windows路径
✅ 用户理解转换的必要性
✅ 文件操作无路径相关错误
✅ 会话中路径格式保持一致

🆘 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系统
用户提及Git Bash或MINGW
发现以
```
/c/
```
、
```
/s/
```
等开头的路径
Edit/Write/Read工具因"file not found"失败
用户在Windows系统下提供带正斜杠的路径
需要在Windows系统下读取/编辑/写入文件

此技能对Windows用户至关重要 - 路径格式错误是Windows系统下Git Bash用户文件操作失败的首要原因。