> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-2772-1782277917413.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Common MCP Errors

> Solutions to common MCP server connection and configuration issues

<Info>
  Looking for a specific error code? See the [error code reference](/troubleshooting/error-codes) — every ErrorCard in the inspector deep-links to a section there.
</Info>

This guide covers common errors you might encounter when working with MCP servers and how to resolve them.

## Connection Issues

### Diagnose a connection failure

Most "failed to connect" / `fetch failed` / `ECONNREFUSED` / `MCP error -32000: Connection closed` / `MCP error -32001: Request timed out` reports come down to one of five root causes. Work through them in order — each step takes seconds.

1. **Is the server actually running?**

   Open a second terminal and run the same command you'd ask Inspector to run. If it exits or prints a stack trace, fix that first — Inspector can only attach to a server that stays alive.

   ```bash theme={null}
   # For STDIO servers — run the same command Inspector would run
   python /Users/yourname/project/server.py
   # or: uv run --directory /Users/yourname/project mcp.py
   # or: npx -y @modelcontextprotocol/server-everything

   # For HTTP servers
   curl -i http://localhost:PORT/mcp
   ```

   A clean stdio process should sit waiting on stdin; a healthy HTTP server should respond with something other than `Connection refused` (the exact code varies — common responses are `405 Method Not Allowed` for `GET`, `406 Not Acceptable` if Accept headers are missing, or `400 Bad Request` if the server expects a session header).

2. **Right port, right path?**

   `ECONNREFUSED 127.0.0.1:5555` means **nothing is listening on that port** — typo, wrong port, or the server is bound to `127.0.0.1` only while you're calling it via a different hostname (or vice versa). `SSE error: Non-200 status code (404)` means the port is correct but the path is wrong: most MCP servers mount under `/mcp` or `/sse`, not `/`.

3. **Right transport selected?**

   In the server card, the transport dropdown must match what your server speaks. STDIO servers won't respond to HTTP attempts and vice versa. If you used a `url:` field in `config.json`, Inspector picks HTTP; if you used `command:` + `args:`, Inspector picks STDIO.

4. **Right auth setting?**

   For local development servers, pick **No Authentication**. If you get `401`, see [Getting 401 Unauthorized errors](#getting-401-unauthorized-errors) below.

5. **Did the server actually finish booting before the handshake?**

   `MCP error -32001: Request timed out` during `initialize` means the server didn't respond to the handshake in time — usually because it's still loading models, opening a database, or waiting on an upstream. Raise the **Request timeout** in **Clients → your client → Request timeout** (default 30,000ms), or reduce the server's startup work.

If all five check out and you still see a failure, copy the full error from the JSON-RPC log into a [GitHub issue](https://github.com/MCPJam/inspector/issues) or [Discord](https://discord.gg/JEnDtz8X6z) thread.

### `(intermediate value).subtle is undefined`

The browser's Web Crypto API (`crypto.subtle`) is only available in **secure contexts** — that means HTTPS, or `http://localhost` / `http://127.0.0.1`. If you're hitting Inspector over a non-localhost HTTP URL (for example, a LAN IP like `http://192.168.1.10:6274`), the browser disables `crypto.subtle` and OAuth/PKCE flows fail.

**Fix:** open Inspector at `http://localhost:6274` or `http://127.0.0.1:6274`, or put HTTPS in front of it. The hosted app and the desktop app are unaffected.

### Server fails to start or connect

* **Use absolute paths**: Specify the full path to your server
  * ✅ Good: `/Users/yourname/project/server.py`
  * ❌ Bad: `./server.py` or `server.py`

* **For `uv` projects**: Use the `--directory` flag with absolute path

  ```bash theme={null}
  uv run --directory /Users/username/weather-mcp mcp.py
  ```

* **Test your command first**: Run the server command manually in a terminal to verify it works before adding it to Inspector

* **For HTTP servers**: Verify the URL is accessible
  * Test with `curl` or a browser first

### "Invalid host header" when connecting to an HTTP server

This response comes from **your MCP server**, not from MCPJam Inspector. The server's HTTP layer is rejecting the request because the `Host` header isn't on its allowlist. Most common culprits:

* **Next.js / webpack-dev-server** — both block unknown hosts by default in dev mode. Add your host to `allowedHosts` (webpack-dev-server) or `experimental.allowedDevOrigins` (Next.js).
* **FastAPI / Starlette (Python)** — `TrustedHostMiddleware` rejects hosts not in `allowed_hosts`. Add the host the inspector is calling from, or temporarily set `allowed_hosts=["*"]` for local testing.
* **Reverse proxies (nginx, Caddy)** — check the `server_name` / `host_match` config.

**Quick check:** test the same URL with `curl http://localhost:PORT/mcp` — if curl gets the same error, it's definitely server-side, not inspector.

## Authentication Issues

### Server fails to connect with authentication errors

**If your server is failing to connect, first verify you've selected the correct authentication option:**

* **No Authentication** - Use this for local or development servers that don't require authentication
* **Bearer Token** - Use this if you already have an API token from the server
* **OAuth 2.0** - Use this for servers that require OAuth authorization flow

### Getting 401 Unauthorized errors

If you're seeing **401 Unauthorized** errors when trying to connect to your server, this typically means the server requires authentication that hasn't been set up yet.

**Solution:**

1. Change your authentication type to **OAuth 2.0** in the server configuration
2. Go through the OAuth authorization flow to obtain credentials
3. Use the OAuth Debugger to troubleshoot any issues with the OAuth process

<Info>
  The OAuth Debugger helps you step through each part of the authorization
  process and identify where things might be going wrong.
</Info>

### OAuth connection failures

When an OAuth flow fails, Inspector surfaces the failure directly in the connection UI so you can diagnose the problem without leaving the Servers tab.

**Connection card** — a banner above the error message identifies the exact OAuth step that failed (for example, "OAuth failed during Token Request").

**Server detail panel** — open the server's detail view to see the full **Last OAuth Trace**, which includes:

* Each OAuth step with its status (pending / success / error) and a short message
* The specific error for any failed step
* An **HTTP History** log of every request and response made during the flow, with sensitive values automatically redacted

Use the trace to pinpoint whether the failure occurred during discovery, client registration, PKCE generation, the authorization redirect, or the token exchange, then cross-reference with the OAuth Debugger for a guided walkthrough of the same steps.

### Toggle shows a re-authentication error for an OAuth server

The enable/connect toggle on a server card or detail modal reuses existing credentials only. If your tokens are expired or missing, the toggle will report a re-authentication error rather than opening the OAuth consent screen.

**Solution:** Use the **Reconnect** button on the server card or detail modal to start a full OAuth flow and obtain new credentials. The toggle is intentionally non-interactive for OAuth to avoid unexpected browser redirects.

### Common Configuration Mistakes

* Missing required environment variables
* Incorrect transport type selection
* Typos in server URLs or commands
* Missing file permissions or executable flags

## Chat Model Limit

### "MCPJam model limit reached" warning

MCPJam provides free frontier models for chat. When you hit the daily usage limit, the chat surface shows a warning:

> **MCPJam model limit reached.** Add your own API key under LLM Providers in Settings to continue now, or try again in *N* minutes.

This is an expected quota state, not an error with your MCP server.

**To continue immediately:**

1. Go to **Settings → LLM Providers**
2. Add an API key for any supported provider (OpenAI, Anthropic, Gemini, etc.)
3. Select that provider's model in the chat model picker

**To wait for the limit to reset:** The warning includes the retry window. Free quota resets daily.

## Desktop app startup failures

### App bounces in the dock and disappears (macOS) or closes immediately

If the desktop app fails to start, it now shows a recovery dialog instead of quitting silently. The dialog offers three options:

* **Reset app data and quit** — removes cached data (`Cache`, `Code Cache`, `GPUCache`, `Local Storage`) from the app's user data folder and relaunches. Use this when the app crashes consistently after an update or when local data appears corrupted.
* **Open logs folder** — opens the folder containing `electron-log` output, then quits. Use this to inspect the error before deciding whether to reset.
* **Quit** — exits without making any changes.

### Port 6274 is already in use

The desktop app defaults to port **6274**. If another process holds that port, the app automatically tries the next available port up to port **6283**. A warning is written to the app logs when a fallback port is used. No action is required — the app starts normally on the fallback port.

If you need to free port 6274 manually, find and stop the process occupying it:

```bash theme={null}
# macOS / Linux
lsof -ti :6274 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 6274).OwningProcess | Stop-Process
```

### App crashes after an automatic update

The desktop app automatically clears stale GPU and HTTP caches (`Cache`, `Code Cache`, `GPUCache`) the first time it launches after a version change. This handles most renderer or GPU process crashes caused by cached data from a previous build. If the app still fails to start after an update, use the **Reset app data and quit** option in the recovery dialog.

## Getting Help

If you're still experiencing issues:

1. **Check server documentation**
   * Review the MCP server's specific documentation
   * Look for known issues or troubleshooting guides

2. **Community support**
   * Join our [Discord](https://discord.gg/JEnDtz8X6z) for community help
   * Check [GitHub Issues](https://github.com/MCPJam/inspector/issues) for similar problems