api-gateway-troubleshooting

Diagnoses failing requests and deployment errors on Google Cloud API Gateway.

23.7k|2.0k|Updated Mar 31, 2026
Ready to run
npx skills add https://github.com/google/skills --skill api-gateway-troubleshooting-google
💬 Prompt for ChatGPT / Claude Chat▼
Please help me install this Agent Skill.
Skill: api-gateway-troubleshooting
Source: https://github.com/google/skills/tree/main/skills/cloud/api-gateway-troubleshooting
Command: npx skills add https://github.com/google/skills --skill api-gateway-troubleshooting-google

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? You have a deployed Google Cloud API Gateway, but requests are failing with 4xx or 5xx errors, timing out, or failing CORS preflight checks. You need to identify whether the problem is in the gateway, the backend, authentication, routing, or infrastructure—and how to fix it. ## Core Features & Use Cases - Request Failure Diagnosis: Determines whether a 401, 403, 404, 502, 503, or 504 error came from the gateway or backend, and why. - Deployment Troubleshooting: Fixes api-configs create, gateways create, and gateways update failures. - Use Case: Your Cloud Run backend is healthy, but callers get 401 errors through the gateway. This Skill reads gateway logs, checks service account IAM roles, and guides you to grant the gateway's service account the invoker role on the backend. ## Quick Start Tell me your project ID, the failing URL or gateway name, the HTTP method and status code you received, and approximately when it failed, and I will read your gateway's logs and diagnose the root cause.

Frequently Asked Questions about api-gateway-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a 401 or 403 error on Google Cloud API Gateway?▼

Read the gateway's request log and check the responseDetails field. If it says via_upstream, the backend rejected the gateway's service account—grant that account the invoker role on the backend. Otherwise, the gateway rejected the caller; verify the API key exists, matches the security definition, and is not restricted to a different project.

Why does api-configs create fail with a service account error?▼

API Gateway uses the default Compute Engine service account if you do not specify one. If that account does not exist, rerun the create command with --backend-auth-service-account={email}. The account must exist and you must have iam.serviceAccounts.actAs on it.

What causes a 504 timeout on API Gateway?▼

The default backend deadline is 15 seconds. If your backend needs longer, increase the deadline in the OpenAPI document up to 600 seconds for non-streaming gateways or 3600 for streaming gateways. Also check that your backend is actually responding and not hung.

How do I enable CORS on API Gateway?▼

Set allowCors: true in the x-google-endpoints extension for OpenAPI 2.0 or on the x-google-endpoint server extension for OpenAPI 3.x. Then create a new API config and deploy it with gateways update. Your backend must reply to OPTIONS preflight requests with the correct Access-Control-* headers.

Why does the gateway log show no entries even though requests are failing?▼

Check that apigateway.googleapis.com, servicemanagement.googleapis.com, and servicecontrol.googleapis.com are enabled in your project. If they are and logs are still empty, the gateway's service account may be deleted or disabled. Verify with gcloud iam service-accounts describe.

Can API Gateway call other Google Cloud APIs as backends?▼

Non-streaming gateways cannot. Streaming-enabled gateways can, but they send an ID token with only the cloud-platform scope. Grant your gateway's service account the role that the target API requires, such as aiplatform.user for Agent Platform endpoints.