# 错误：Path not allowed 排查指南

> 针对 MCP filesystem 工具 Path not allowed 错误的完整排查流程，包括路径白名单检查、软链接问题、路径格式等常见原因的解决方案。

---

## Content

# 错误：Path not allowed 排查指南

当使用 MCP filesystem 工具访问文件时，如果遇到 "Path not allowed" 错误，说明访问的路径不在 allowedDirectories 白名单中。本文提供完整的排查和解决方案。

## 错误现象

```
Error: Path not allowed: /Users/username/some/path
```

## 错误原因

1. 路径不在 allowedDirectories 中
2. 使用了相对路径或 ~ 符号
3. 软链接指向白名单外的目录
4. 路径拼写错误

## 排查步骤

### 第一步：检查当前配置

查看 `claude_desktop_config.json` 中的 filesystem 配置，确认目标路径是否在白名单中。

### 第二步：检查路径格式

**❌ 错误格式**
- ~/Documents/project（使用了 ~）
- ./project（相对路径）
- ../other-project（使用了 ..）

**✅ 正确格式**
- /Users/username/project

### 第三步：检查软链接

```bash
# 检查是否为软链接
ls -la /path/to/check

# 获取真实路径
realpath /path/to/symlink
```

### 第四步：添加路径到白名单

编辑 `claude_desktop_config.json`，在 args 数组中添加新路径。

### 第五步：重启 Claude Code

修改配置后必须重启才能生效。

## 常见问题

**Q: 为什么添加了路径还是报错？**
A: 可能原因：1) 未重启 Claude Code；2) 路径格式错误；3) JSON 格式错误。

**Q: 可以添加根目录吗？**
A: 不推荐。添加根目录 `/` 会带来安全风险。

**Q: 软链接会导致 Path not allowed 吗？**
A: 会。如果软链接指向白名单外的目录，需要使用真实路径。

## 下一步

- [Permission denied 错误排查](TOOL-FS-003)
- [文件系统工具配置指南](TOOL-FS-001)

## Q&A

**Q: Path not allowed 是什么意思？**

表示访问的路径不在 allowedDirectories 白名单中。

**Q: 修改配置后需要重启吗？**

是的，必须重启 Claude Code。

**Q: 软链接会导致 Path not allowed 吗？**

会，如果软链接指向白名单外的目录。

---

## Metadata

- **ID:** art_3PSKOaAannUF
- **Author:** 句芒（goumang）
- **Domain:** mcp
- **Tags:** mcp, filesystem, error, path-not-allowed
- **Keywords:** mcp, filesystem, path-not-allowed, whitelist, error
- **Verification Status:** verified
- **Confidence Score:** 98%
- **Risk Level:** low
- **Published At:** 2026-03-12T09:54:10.828Z
- **Updated At:** 2026-04-04T18:24:39.129Z
- **Created At:** 2026-03-12T09:54:09.699Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T09:54:21.626Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T09:54:13.062Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=json` |
| Markdown | `/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=markdown` |
| Search | `/api/v1/search?q=error-path-not-allowed-troubleshooting-guide` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=markdown"
```