{
  "id": "art_3PSKOaAannUF",
  "slug": "error-path-not-allowed-troubleshooting-guide",
  "author": "句芒（goumang）",
  "title": "错误：Path not allowed 排查指南",
  "summary": "针对 MCP filesystem 工具 Path not allowed 错误的完整排查流程，包括路径白名单检查、软链接问题、路径格式等常见原因的解决方案。",
  "content": "# 错误：Path not allowed 排查指南\n\n当使用 MCP filesystem 工具访问文件时，如果遇到 \"Path not allowed\" 错误，说明访问的路径不在 allowedDirectories 白名单中。本文提供完整的排查和解决方案。\n\n## 错误现象\n\n```\nError: Path not allowed: /Users/username/some/path\n```\n\n## 错误原因\n\n1. 路径不在 allowedDirectories 中\n2. 使用了相对路径或 ~ 符号\n3. 软链接指向白名单外的目录\n4. 路径拼写错误\n\n## 排查步骤\n\n### 第一步：检查当前配置\n\n查看 `claude_desktop_config.json` 中的 filesystem 配置，确认目标路径是否在白名单中。\n\n### 第二步：检查路径格式\n\n**❌ 错误格式**\n- ~/Documents/project（使用了 ~）\n- ./project（相对路径）\n- ../other-project（使用了 ..）\n\n**✅ 正确格式**\n- /Users/username/project\n\n### 第三步：检查软链接\n\n```bash\n# 检查是否为软链接\nls -la /path/to/check\n\n# 获取真实路径\nrealpath /path/to/symlink\n```\n\n### 第四步：添加路径到白名单\n\n编辑 `claude_desktop_config.json`，在 args 数组中添加新路径。\n\n### 第五步：重启 Claude Code\n\n修改配置后必须重启才能生效。\n\n## 常见问题\n\n**Q: 为什么添加了路径还是报错？**\nA: 可能原因：1) 未重启 Claude Code；2) 路径格式错误；3) JSON 格式错误。\n\n**Q: 可以添加根目录吗？**\nA: 不推荐。添加根目录 `/` 会带来安全风险。\n\n**Q: 软链接会导致 Path not allowed 吗？**\nA: 会。如果软链接指向白名单外的目录，需要使用真实路径。\n\n## 下一步\n\n- [Permission denied 错误排查](TOOL-FS-003)\n- [文件系统工具配置指南](TOOL-FS-001)",
  "lang": "zh",
  "domain": "mcp",
  "tags": [
    "mcp",
    "filesystem",
    "error",
    "path-not-allowed"
  ],
  "keywords": [
    "mcp",
    "filesystem",
    "path-not-allowed",
    "whitelist",
    "error"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 98,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "Path not allowed 是什么意思？",
      "answer": "表示访问的路径不在 allowedDirectories 白名单中。"
    },
    {
      "id": "qa_002",
      "question": "修改配置后需要重启吗？",
      "answer": "是的，必须重启 Claude Code。"
    },
    {
      "id": "qa_003",
      "question": "软链接会导致 Path not allowed 吗？",
      "answer": "会，如果软链接指向白名单外的目录。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmnajrcq000mw5z0ywaqll0u",
      "articleId": "art_3PSKOaAannUF",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T09:54:21.626Z"
    },
    {
      "id": "cmmnajkqt000kw5z0aoga4sxx",
      "articleId": "art_3PSKOaAannUF",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T09:54:13.062Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T09:54:10.828Z",
  "updatedAt": "2026-04-04T18:24:39.129Z",
  "createdAt": "2026-03-12T09:54:09.699Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=error-path-not-allowed-troubleshooting-guide",
      "json": "/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=json&lang=zh",
      "markdown": "/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/error-path-not-allowed-troubleshooting-guide?format=json&lang=zh\""
  }
}