{"record":{"id":"291d937bd09a42a3","repo":"upstash/context7","slug":"proxy-error","errorCode":"proxy_error","errorMessage":"Failed to proxy authorization server metadata","messagePattern":"Failed to proxy authorization server metadata","errorType":"http","errorClass":null,"httpStatus":502,"severity":"error","filePath":"packages/mcp/src/index.ts","lineNumber":505,"sourceCode":"    app.get(\n      \"/.well-known/oauth-authorization-server\",\n      async (_req: express.Request, res: express.Response) => {\n        const authServerUrl = OAUTH_AUTH_SERVER_URL;\n\n        try {\n          const response = await fetch(`${authServerUrl}/.well-known/oauth-authorization-server`);\n          if (!response.ok) {\n            console.error(\"[OAuth] Upstream error:\", response.status);\n            return res.status(response.status).json({\n              error: \"upstream_error\",\n              message: \"Failed to fetch authorization server metadata\",\n            });\n          }\n          const metadata = await response.json();\n          res.json(metadata);\n        } catch (error) {\n          console.error(\"[OAuth] Error fetching OAuth metadata:\", error);\n          res.status(502).json({\n            error: \"proxy_error\",\n            message: \"Failed to proxy authorization server metadata\",\n          });\n        }\n      }\n    );\n\n    // OpenAI Apps SDK domain verification challenge\n    app.get(\n      \"/.well-known/openai-apps-challenge\",\n      (_req: express.Request, res: express.Response) => {\n        if (!OPENAI_APPS_CHALLENGE_TOKEN) {\n          return res.status(404).json({\n            error: \"not_found\",\n            message: \"Endpoint not found.\",\n          });\n        }\n        res.type(\"text/plain\").send(OPENAI_APPS_CHALLENGE_TOKEN);","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/upstash/context7/blob/c3248289c2ad431a9f34849a3f3d047fc4400373/packages/mcp/src/index.ts#L487-L523","documentation":"The `/.well-known/oauth-authorization-server` route proxies `fetch(`${authServerUrl}/.well-known/oauth-authorization-server`)`. When the fetch itself throws (DNS failure, TLS error, timeout), the client gets HTTP 502 with `error: \"proxy_error\"` and this message. An upstream non-ok status is a different error (`upstream_error` with the upstream status).","triggerScenarios":"AUTH_SERVER_URL unreachable — bad DNS, firewall/egress rules, TLS failure, or the authorization server being down; container without outbound network access.","commonSituations":"Misconfigured AUTH_SERVER_URL env var; auth-server outage; self-hosted deployments with restricted egress; Kubernetes NetworkPolicy blocking the hop.","solutions":["Verify AUTH_SERVER_URL is correct and reachable from the MCP server container (curl it)","Check the auth server's health and retry once it is up","Open egress for the MCP server to the auth server host/port","If TLS fails, install the proper CA in the server image"],"exampleFix":"# before: wrong env\nAUTH_SERVER_URL=https://auth.internal\n\n# after: correct, reachable issuer\nAUTH_SERVER_URL=https://auth.corp.example.com","handlingStrategy":"retry","validationCode":"// Operator: verify the upstream is up before clients depend on it\nconst res = await fetch(`${AUTH_SERVER_URL}/.well-known/oauth-authorization-server`);\nif (!res.ok) throw new Error(`auth server metadata unreachable (HTTP ${res.status})`);","typeGuard":"function isProxyError(body: unknown): boolean {\n  return (body as any)?.error === 'proxy_error';\n}","tryCatchPattern":"const res = await fetch('/.well-known/oauth-authorization-server');\nif (res.status === 502) {\n  const body = await res.json();\n  if (body?.error === 'proxy_error') { await sleep(2000); return retry(); } // auth server blip\n}","preventionTips":["Health-check AUTH_SERVER_URL from the MCP server container at startup","Allow egress from the MCP server to the auth server host in network policies","Serve the metadata from the same origin when possible to remove the proxy hop"],"tags":["mcp","oauth","proxy","bad-gateway","network"],"backgroundTag":"upstream-bad-gateway","analyzedSha":"c3248289c2ad431a9f34849a3f3d047fc4400373","analyzedAt":"2026-08-18T18:00:18.510Z","schemaVersion":2},"datasetVersion":"2026-08-24T22:17:12.610Z"}