Skip to main content

​
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: 
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 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:
# 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.
  1. 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:
.env
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: 
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.

​
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 with your error output and we’ll help debug.