> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpblacksmith.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to resolve them.

## Generation issues

### "Specification validation failed"

Your OpenAPI specification has structural issues. Run the Validation check in the dashboard to see specific errors. Common causes:

* Missing `paths` or `info` fields
* Broken `$ref` references pointing to non-existent schemas
* Invalid OpenAPI version identifier

### Generation succeeds but some operations are missing

Operations may be skipped if they:

* Have no defined HTTP method
* Have duplicate operation IDs (the second is renamed with a `_2` suffix)
* Reference undefined schemas that can't be resolved

Check the generation console output for warnings.

## Runtime issues

### "ModuleNotFoundError"

Dependencies aren't installed. Run:

```bash theme={null}
pip install -r requirements.txt
```

If using a virtual environment, make sure it's activated.

### "Connection refused" or timeout errors

The target API is unreachable. Check:

* `BASE_URL` in `.env` is correct
* Your network can reach the API (try `curl` or a browser)
* The API isn't rate-limiting you (check for HTTP 429 responses in logs)

### Authentication errors (401 / 403)

The most common cause is missing or incorrect credentials in your `.env` file. The generated server reads credentials from environment variables — if they're empty or wrong, requests will be rejected by the target API.

* Open the `.env` file and verify all credential fields are filled in with valid values
* Make sure the variable names match what the generated code expects (they're pre-configured — just fill in the values)
* For API Key or Bearer authentication, confirm the key/token is active and not expired
* See [Authentication](/server/authentication) for `.env` examples for each authentication type

**For OAuth2 / OIDC specifically:**

* Ensure `OAUTH2_CLIENT_ID` and `OAUTH2_CLIENT_SECRET` are correct and belong to an active OAuth application
* Verify the API is enabled in your provider's developer console (e.g., Google Cloud Console, Azure Portal)
* Select valid scopes for your use case and provide them in `.env` as a comma-separated list (e.g., `OAUTH2_SCOPES=read,write`)
* Delete `oauth2_tokens.json` to force re-authorization if tokens become invalid

**OAuth2 callback port (authorization code and implicit flows):**

The server starts a temporary local HTTP server to receive the OAuth callback during authorization. This requires the callback port to be free and the redirect URI to match between your server and OAuth provider.

1. **Check the port is free** — the default callback port is `8080` (configured via `OAUTH2_CALLBACK_PORT` in `.env`). If another process is using this port, the authorization flow fails silently and requests go out unauthenticated. Check with:

```bash theme={null}
# Linux / macOS
lsof -i :8080
# or
ss -tlnp | grep 8080
```

If the port is occupied, either stop the conflicting process or change `OAUTH2_CALLBACK_PORT` in `.env` to a free port.

2. **Redirect URI must match** — your OAuth provider's allowed redirect URIs must include `http://localhost:<port>/callback` where `<port>` matches `OAUTH2_CALLBACK_PORT` in `.env`. For example, with the default port:

```
http://localhost:8080/callback
```

Add this to your OAuth application's redirect URIs in the provider's developer console (e.g., Google Cloud Console → Credentials → OAuth 2.0 Client → Authorized redirect URIs).

### "Rate limit exceeded"

This can come from two sources:

**Local rate limiter** — The generated server includes an optional local rate limiter that caps outgoing requests per second. This is disabled by default. If you enabled it during generation (Generation tab → Config → Advanced settings → Security: Enable Rate Limiting), you can adjust the limit in `.env` or disable it at runtime:

```bash .env theme={null}
RATE_LIMIT_REQUESTS_PER_SECOND=20    # adjust the limit (default: 10)
```

To disable rate limiting at runtime, start the server with the `--rate-limiting disabled` flag:

```bash theme={null}
python server.py --rate-limiting disabled
```

**Target API rate limiting** — The upstream API is rejecting your requests (HTTP 429). Check the API's documentation for rate limits and reduce your request frequency.

### Circuit breaker is open

The target API has been failing consistently. The circuit breaker blocks requests to prevent cascading failures. Wait for the timeout period (default 60 seconds) or restart the server to reset the circuit breaker state.

## MCP client issues

### Tools don't appear in your MCP client

See [Connecting to AI Agents — Troubleshooting](/deployment/connecting-agents#troubleshooting).

### Tools appear but return errors

Run `python server.py` directly in a terminal to see detailed error output. Common causes:

* Missing or incorrect credentials in `.env`
* API returning unexpected response format
* Network issues between your machine and the API

## Still stuck?

[Contact us](https://mcpblacksmith.com/contact) with your error output and we'll help debug.