Troubleshooting agents

Symptom	Likely cause	Fix
401 with WWW-Authenticate: Bearer resource_metadata=...	Missing, expired or revoked token, or an OAuth token for another resource	Check that the agent process can see the environment variable and that the token starts with igw_live_ or igw_test_. OAuth tokens for MCP need resource=<origin>/mcp.
Codex shows the server as needing OAuth, or codex mcp login fails	No bearer token was found, so Codex fell back to OAuth discovery	Set bearer_token_env_var or http_headers_helper, then restart Codex. Don’t use codex mcp login with the Gateway.
Tools stop working after about 15 minutes	A client credentials token was pasted in as a static token	Use an installation token, or the header helper so tokens refresh.
406 “Accept must include application/json and text/event-stream”	The client isn’t a Streamable HTTP client	Use a client that supports Streamable HTTP, or send that Accept header.
403 “Origin denied”	The request came from a browser page on another origin	Run the client on a server or desktop.
405 on GET /mcp	Expected: the server has no event stream	Clients should keep using POST.
A tool you expect is missing	The credential lacks a scope, data flag, unrestricted policy or author mapping	Call gateway_context to see current grants, and capabilities_list for a website.
Tool error not_found (404)	The website isn’t granted, or the resource isn’t accessible	Use a website from websites_list and IDs it returned.
Tool error with retry_after, or HTTP 429	Quota reached	Wait for the given number of seconds.
Tool error service_unavailable (503) or connector_response_invalid (502)	The website’s cluster or connector is unavailable or out of date	Retry later. Report the request_id if it persists.

When you contact support, include the request_id from the error. It’s also returned in the X-Request-Id header.