Error catalog

Each entry starts from the text the client printed, lists the likely causes from most to least common, and gives the order to check them in. Every message on these pages was either reproduced by us or quoted from a first-party source; each entry says which.

Find an error

Paste an error message

A client log or terminal output is fine; paste the whole block. Matching happens in your browser and nothing is uploaded.

All entries

Server startup and stdio

• MCP error -32000: Connection closedMost likely: The server crashes on start
• spawn npx ENOENTMost likely: The command is not on the client’s PATH
• MCP error -32001: Request timed outMost likely: The server never answers
• Unexpected token … is not valid JSONMost likely: Your code logs to stdout
• listen EADDRINUSE: address already in useMost likely: An earlier copy is still running
• ERR_UNKNOWN_FILE_EXTENSION: Unknown file extension ".ts"Most likely: The client runs an older Node.js
• ModuleNotFoundError: No module named 'mcp'Most likely: The client starts a different Python

HTTP transport

• Not Acceptable: Client must accept both application/json and text/event-streamMost likely: The request has no or a narrow Accept header
• 405 Method not allowed on GET /mcpMost likely: You opened the endpoint in a browser
• Bad Request: Missing session IDMost likely: The request has no MCP-Protocol-Version header
• Unsupported Media Type: Content-Type must be application/json (415)Most likely: The request is not sent as JSON
• Invalid Host header (403 or 421)Most likely: A proxy or container changes the Host
• Invalid Origin header (403)Most likely: A web page calls the server
• Access to fetch at … has been blocked by CORS policyMost likely: The server sends no CORS headers
• Error POSTing to endpoint (HTTP 404)Most likely: The URL path is wrong
• TypeError: fetch failed (ECONNREFUSED)Most likely: The server is not running on that port

Protocol, versions and tools

• Version negotiation failed: the server did not offer pinned protocol versionMost likely: The server only speaks 2025 versions
• Unsupported protocol version (-32022)Most likely: A TypeScript server uses the old transport wiring
• Bad Request: the request headers and body disagree (-32020)Most likely: A required header is missing
• Method not found (-32601)Most likely: The server does not offer that feature
• Input validation error: Invalid arguments for toolMost likely: The model sent the wrong type or shape
• Output validation error: Invalid structured content for toolMost likely: The handler returns a different shape
• Tool … not found (-32602) / Unknown toolMost likely: The client uses an old tool list
• Resource not found (-32602, formerly -32002)Most likely: The URI is not one the server serves

Client configuration

• MCP tool call requires approval, but approval policy is neverMost likely: Codex exec cannot ask you
• Codex: TOML parse error in config.tomlMost likely: A Windows path inside double quotes
• Codex: MCP client timed out after 30 secondsMost likely: The server is slow to start

SDK upgrades

• No module named 'mcp.server.fastmcp'Most likely: SDK 2.x is installed and the code is for 1.x
• Cannot find package '@modelcontextprotocol/sdk'Most likely: v1 import paths with v2 installed

Authorization

• 401 Unauthorized / invalid_token from an MCP serverMost likely: The client sends no token

If your error is not here, start with the stdio checklist or where to find the logs.