[
  {
    "slug": "spawn-npx-enoent",
    "code": "ENOENT",
    "title": "spawn npx ENOENT / command not found",
    "category": "Environment & Runtime",
    "severity": "Critical",
    "symptom": "AI client crashes or logs 'Error: spawn npx ENOENT' immediately when trying to launch a configured MCP server.",
    "cause": "The AI host application (Claude Desktop, Cursor, etc.) was launched in a graphical desktop environment that does not inherit your terminal's user $PATH, or Node.js is not installed globally.",
    "quickFix": "Replace 'command': 'npx' with the absolute path to your npx binary (e.g. C:/Program Files/nodejs/npx.cmd on Windows or /usr/local/bin/npx on macOS).",
    "osCommands": {
      "mac": "# Find your exact npx binary location:\nwhich npx\n# Example output: /usr/local/bin/npx or /opt/homebrew/bin/npx",
      "windows": "# Find your exact npx.cmd binary location in PowerShell:\nwhere.exe npx.cmd\n# Example output: C:\\Program Files\\nodejs\\npx.cmd",
      "linux": "# Find npx binary path:\nwhich npx\n# Example output: /usr/bin/npx"
    },
    "sampleFixConfig": "{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"C:/Program Files/nodejs/npx.cmd\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:/Users/name/sandbox\"]\n    }\n  }\n}"
  },
  {
    "slug": "json-rpc-32603-internal-error",
    "code": "-32603",
    "title": "JSON-RPC error -32603: Internal error (STDOUT Pollution)",
    "category": "Protocol & Serialization",
    "severity": "High",
    "symptom": "Tools fail to list or fail during execution with generic error code -32603.",
    "cause": "The MCP server wrote non-JSON debug strings to standard output (STDOUT) instead of standard error (STDERR). In stdio transport, STDOUT is strictly reserved for JSON-RPC messages; any `console.log()` breaks JSON parsing.",
    "quickFix": "Switch all logging inside your custom MCP server from `console.log()` to `console.error()`. For Python servers, write logs exclusively to `sys.stderr`.",
    "osCommands": {
      "mac": "# Check MCP host logs for raw output:\ntail -n 50 ~/Library/Logs/Claude/mcp.log",
      "windows": "# Check Claude logs in PowerShell:\nGet-Content -Path $env:APPDATA\\Claude\\logs\\mcp.log -Tail 50",
      "linux": "# Tail Linux MCP logs:\ntail -n 50 ~/.config/Claude/logs/mcp.log"
    },
    "sampleFixConfig": "// In TypeScript MCP Server:\n// ❌ WRONG: console.log(\"Server starting...\");\n// ✅ CORRECT:\nconsole.error(\"Server starting on stdio transport...\");"
  },
  {
    "slug": "json-rpc-32602-invalid-params",
    "code": "-32602",
    "title": "JSON-RPC error -32602: Invalid params",
    "category": "Protocol & Serialization",
    "severity": "Medium",
    "symptom": "Server rejects tool invocation stating arguments do not match schema.",
    "cause": "The AI model passed arguments with incorrect data types (e.g. string instead of integer or array), or omitted a required parameter defined in inputSchema.",
    "quickFix": "Inspect the tool's inputSchema with tools/list and ensure all required fields match their declared types.",
    "osCommands": {
      "mac": "# Inspect tool schema via MCP inspector:\nnpx @modelcontextprotocol/inspector",
      "windows": "# Inspect tool schema via MCP inspector:\nnpx @modelcontextprotocol/inspector",
      "linux": "# Inspect tool schema via MCP inspector:\nnpx @modelcontextprotocol/inspector"
    },
    "sampleFixConfig": "// Ensure payload arguments match required properties\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 12,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"query_database\",\n    \"arguments\": {\n      \"limit\": 10 // Number, not string \"10\"\n    }\n  }\n}"
  },
  {
    "slug": "windows-backslash-json-parse-error",
    "code": "-32700",
    "title": "JSON-RPC error -32700: Parse error / Invalid Windows backslashes",
    "category": "Configuration Syntax",
    "severity": "High",
    "symptom": "Config file fails to load or server crashes on startup with 'SyntaxError: Bad escaped character in JSON'.",
    "cause": "Single backslashes used in Windows file paths (e.g. 'C:\\Projects') violate JSON string escape rules.",
    "quickFix": "Replace single backslashes with forward slashes (e.g. 'C:/Projects') or double-escaped backslashes ('C:\\\\Projects').",
    "osCommands": {
      "mac": "# Not applicable to macOS",
      "windows": "# Format Windows paths with forward slashes in JSON:\n\"args\": [\"C:/Projects/my-app\"]",
      "linux": "# Not applicable to Linux"
    },
    "sampleFixConfig": "{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:/Projects/workspace\"]\n    }\n  }\n}"
  },
  {
    "slug": "sse-connection-closed",
    "code": "SSE_CLOSED",
    "title": "SSE connection closed prematurely / EOF",
    "category": "Network & Transport",
    "severity": "High",
    "symptom": "Remote SSE MCP servers disconnect intermittently or fail to keep long-running tool calls open.",
    "cause": "Reverse proxies (Cloudflare, Nginx, ALB) or corporate firewalls terminate idle HTTP streaming connections after 60–100 seconds when keep-alive heartbeats are missing.",
    "quickFix": "Implement a 15-second ping/heartbeat comment (`: keep-alive\\n\\n`) on the SSE endpoint and disable proxy buffering (`X-Accel-Buffering: no`).",
    "osCommands": {
      "mac": "# Test SSE stream headers with curl:\ncurl -N -H \"Accept: text/event-stream\" https://your-server.com/sse",
      "windows": "# Test SSE stream endpoint:\ncurl.exe -N -H \"Accept: text/event-stream\" https://your-server.com/sse",
      "linux": "# Test SSE stream endpoint:\ncurl -N -H \"Accept: text/event-stream\" https://your-server.com/sse"
    },
    "sampleFixConfig": "// Nginx Proxy Configuration:\nlocation /sse {\n    proxy_pass http://localhost:8000;\n    proxy_set_header Connection '';\n    proxy_http_version 1.1;\n    chunked_transfer_encoding off;\n    proxy_buffering off;\n    proxy_cache off;\n}"
  },
  {
    "slug": "github-403-saml-sso",
    "code": "HTTP 403",
    "title": "GitHub MCP 403: Resource protected by organization SAML",
    "category": "Authentication",
    "severity": "Medium",
    "symptom": "GitHub MCP server fails to read enterprise repositories with 403 Forbidden error.",
    "cause": "Your Personal Access Token (PAT) has not been authorized for SAML Single Sign-On (SSO) by the target GitHub Organization.",
    "quickFix": "Visit GitHub Settings → Personal Access Tokens → Click 'Configure SSO' next to your token and authorize it for your organization.",
    "osCommands": {
      "mac": "# Verify GitHub PAT authorization:\ncurl -H \"Authorization: token ghp_...\" https://api.github.com/user/orgs",
      "windows": "# Verify GitHub PAT authorization:\ncurl.exe -H \"Authorization: token ghp_...\" https://api.github.com/user/orgs",
      "linux": "# Verify GitHub PAT authorization:\ncurl -H \"Authorization: token ghp_...\" https://api.github.com/user/orgs"
    },
    "sampleFixConfig": "{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"${GITHUB_SAML_AUTHORIZED_TOKEN}\"\n      }\n    }\n  }\n}"
  },
  {
    "slug": "tool-call-timeout-60s",
    "code": "TIMEOUT",
    "title": "Tool call timed out after 60000ms",
    "category": "Performance & Database",
    "severity": "Medium",
    "symptom": "Long-running database queries, video processing, or web scraping tool calls abort with a timeout error.",
    "cause": "Default client timeouts limit tool execution duration to 60 seconds before concluding the stdio process is unresponsive.",
    "quickFix": "Split heavy queries into paginated chunks or implement asynchronous polling jobs where the tool returns a job ID immediately.",
    "osCommands": {
      "mac": "# Check query plan latency before running in MCP:\npsql $DATABASE_URL -c \"EXPLAIN ANALYZE SELECT ...;\"",
      "windows": "# Check query plan latency:\npsql.exe $env:DATABASE_URL -c \"EXPLAIN ANALYZE SELECT ...;\"",
      "linux": "# Check query plan latency:\npsql $DATABASE_URL -c \"EXPLAIN ANALYZE SELECT ...;\""
    },
    "sampleFixConfig": "// In your MCP server tool handler:\n// Return job token immediately rather than hanging for 120 seconds\nreturn {\n  content: [{ type: \"text\", text: \"Job submitted with ID: task_9821. Call check_status to poll.\" }]\n};"
  },
  {
    "slug": "postgres-ssl-required",
    "code": "SSL_ERR",
    "title": "PostgreSQL: no pg_hba.conf entry for host / SSL required",
    "category": "Database Integration",
    "severity": "High",
    "symptom": "PostgreSQL MCP server fails to connect to Supabase, Neon, AWS RDS, or Render databases.",
    "cause": "Cloud PostgreSQL instances reject unencrypted plaintext SSL connections by default.",
    "quickFix": "Append '?sslmode=require' to your connection URL in the MCP configuration args or env block.",
    "osCommands": {
      "mac": "# Test secure DB connection:\npsql \"postgresql://user:pass@ep-host.neon.tech/neondb?sslmode=require\"",
      "windows": "# Test secure DB connection in PowerShell:\npsql.exe \"postgresql://user:pass@ep-host.neon.tech/neondb?sslmode=require\"",
      "linux": "# Test secure DB connection:\npsql \"postgresql://user:pass@ep-host.neon.tech/neondb?sslmode=require\""
    },
    "sampleFixConfig": "{\n  \"mcpServers\": {\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-postgres\",\n        \"postgresql://user:password@ep-host.neon.tech/neondb?sslmode=require\"\n      ]\n    }\n  }\n}"
  },
  {
    "slug": "filesystem-permission-denied-eacces",
    "code": "EACCES",
    "title": "Filesystem MCP: Permission Denied / Outside Root Sandbox",
    "category": "Security & Sandbox",
    "severity": "High",
    "symptom": "Filesystem server returns error: Access denied to path outside allowed directory boundaries.",
    "cause": "The tool attempted to read or write a file outside the directories specified in the server arguments list.",
    "quickFix": "Add the directory or parent directory to the args array in your client configuration.",
    "osCommands": {
      "mac": "# Check directory permissions:\nls -la /path/to/target",
      "windows": "# Check directory permissions:\nGet-Acl -Path C:\\path\\to\\target",
      "linux": "# Check directory permissions:\nls -la /path/to/target"
    },
    "sampleFixConfig": "{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"C:/Projects/main-app\",\n        \"C:/Projects/shared-libs\"\n      ]\n    }\n  }\n}"
  }
]