Common Issues

Use this guide to quickly diagnose and resolve the most frequent issues when building or operating MCP Servers in Infragate. Each section includes symptoms, likely causes, and concrete fixes—plus links to deeper docs.

Server is outdated (Update Available)

Symptoms: Tools fail unexpectedly, behavior differs from docs, banner shows “Update Available”.

Fix:

• Open your MCP Server in the console and go to the Overview tab.
• If you see the yellow “Update Available” banner, click “Update Version”.
• Wait until status returns to READY, then retry your request.
• See: Getting Started → Your First MCP Server for managing versions.

401 Unauthorized or missing auth headers

Symptoms: 401 Unauthorized, errors like “missing x-api-key” or downstream 401s.

Fix (depends on Authorization Type):

• Authorization: API Key → Every request must include header x-api-key: <your-server-api-key>.
• Authorization: Bearer Passthrough → Include BOTH:
  • x-api-key: <your-server-api-key> (validated by Infragate)
  • Authorization: Bearer <token> (forwarded unchanged to downstream APIs)
• Authorization: None → Remove auth headers unless required by the downstream service.
• See: Getting Started → Authentication & Authorization.

HTTP API data source still returns 401/403

Symptoms: Downstream API denies access even when you set Authorization.

Fix:

• If server Authorization is Bearer Passthrough, set the HTTP data source auth to None and rely on the forwarded Authorization header from the request.
• Otherwise, configure the data source’s auth method to match the API (API Key, Bearer, Basic, OAuth2 Client Credentials, AWS SigV4).
• See: Getting Started → Authentication & Authorization.

SQL Tool call fails due to parameters

Symptoms: Validation errors, missing/invalid parameter messages, unexpected SQL behavior.

Fix:

• Provide all required parameters with correct types and exact names defined in the tool.
• For SQL tools, prefer Prepared Statements and use named placeholders like :param.
• Do not end SQL with a semicolon; some drivers reject trailing semicolons.

Database connection errors

Symptoms: Connection refused, timeouts, auth failures, cannot reach private DB.

Fix:

• Verify hostname, port, database name, username, and password.
• Use a read-only database user for safety.
• For private networks, enable SSH Tunneling on the data source and provide bastion host details.
• Ensure the bastion host can reach the DB (security groups/firewall) and your private key is valid (base64 if required).
• See: Guides → Databases → SSH Tunneling.

SSH tunneling does not establish

Symptoms: Timeouts when tunneling, errors on opening SSH channel.

Fix:

• Bastion host is reachable on port 22 from the platform.
• DB allows inbound from bastion host on the DB port.
• SSH username matches the bastion image (e.g., ec2-user for Amazon Linux).
• Private key content and passphrase (if any) are correct; provide base64 where prompted.
• RDS/DB endpoint and port are the internal/private ones reachable from the bastion.

Slow responses or cold starts

Symptoms: First request after idle is slow; intermittent latency spikes.

Fix:

• Minimize heavy global initialization and reduce dependency size in custom functions.
• Reuse outbound connections (HTTP, DB) within the same instance where possible.
• Consider memory/CPU tuning if available; more resources can reduce execution time.
• See: Configuration → Scaling and Monitoring.

Intermittent throttling or queueing under load

Symptoms: Spikes cause timeouts or increased latency; occasional failed requests.

Fix:

• Platform scales instances with concurrency; brief queuing can occur during bursts.
• Implement client-side retries with exponential backoff and jitter.
• Watch metrics to understand concurrency and limits; adjust workload patterns if needed.
• See: Configuration → Scaling.

No logs or hard to debug failures

Symptoms: Hard to pinpoint which tool/request failed.

Fix:

• Use the Monitoring tab to view gateway metrics and structured logs (14-day retention).
• Filter logs by tool or data source; copy Request ID to correlate events.
• Add meaningful logs in custom functions around external calls and parameter parsing.
• See: Configuration → Monitoring.

Environment variables not available in functions

Symptoms: process.env.* is undefined or missing in custom functions.

Fix:

• Set environment variables at the tool level in the console and ensure names match your code.
• Avoid committing secrets; rotate values if misconfigured.
• See: Guides → Functions → Environment Variables.

Function dependency errors at runtime

Symptoms: Import/resolve errors, long cold starts, timeouts on first run.

Fix:

• Pin versions and use supported import specifiers (e.g., npm:package@version where applicable).
• Keep dependency sets lean to reduce cold start time.
• Validate external network access requirements for SDKs you import.
• See: Guides → Functions → External Dependencies.

General checklist before opening an issue

• Server status is READY and on latest version.
• Endpoint URL is correct and reachable from your client/network.
• Auth headers match the server’s Authorization Type.
• Tool parameters are complete and typed correctly.
• Data source authentication and connectivity are correct (and SSH tunnel configured if needed).
• Monitoring logs reviewed, with Request ID captured.

Still need help?

If issues persist after the above, gather the Request ID, server endpoint, the tool name, and a timestamp, then head to Troubleshooting → Getting Help.