SkillAgentSearch skills...

api-gateway-troubleshooting

Diagnoses failing requests and deployment errors on Google Cloud API Gateway

Install / Use

npx skills add google/skills --skill api-gateway-troubleshooting

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

95/100

Category

Operations

Supported Platforms

Universal

Our assessment of api-gateway-troubleshooting

api-gateway-troubleshooting scores 95/100 on our quality scale, 90th of 745 Operations skills we index (top 13%).

Its SKILL.md is 19 KB long, well organised into 19 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.

With 20,340 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
18/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so api-gateway-troubleshooting is actively maintained.
  • Our last check on 2026-11-15 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-15. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

api-gateway-troubleshooting compared with similar skills

All 4 of these similar skills score higher than api-gateway-troubleshooting; compare them before choosing.

SkillScoreStarsUpdatedFormat
api-gateway-troubleshooting (this skill)by google9520.3k54d agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP Server
crawl4aiby unclecode10087.4k3d agoMCP Server

Frequently asked questions

How do I install api-gateway-troubleshooting?
Run npx skills add google/skills --skill api-gateway-troubleshooting. The install tabs above show the steps for each supported agent.
Which AI agents does api-gateway-troubleshooting work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is api-gateway-troubleshooting safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is api-gateway-troubleshooting still maintained?
The repository was last updated about 2 months ago, so api-gateway-troubleshooting is actively maintained.

name: api-gateway-troubleshooting metadata: version: "1.0.0" category: Serverless description: >- Diagnoses failing requests and deployment errors on Google Cloud API Gateway. Use when calls through a gateway return 4xx or 5xx errors, including 429 and other quota errors, time out, or fail a CORS preflight; when api-configs create fails with a service account, concurrency, or limit error, or gateways create or gateways update fails; when a custom domain, load balancer, or TLS finding involves a gateway; or when the user asks if Google is at fault. Don't use for Apigee, Cloud Endpoints, or GKE Gateway API. For OpenAPI errors from api-configs create, use api-gateway-openapi-spec-authoring; for setting up or changing API keys, JWTs, or quotas, use api-gateway-backend-security-and-rate-limiting; for MCP /mcp errors, use api-gateway-mcp-server.

API Gateway Troubleshooting

Use this skill to find out why requests to a deployed Google Cloud API Gateway fail and how to fix them. Work only from three sources of evidence:

  1. Public Google Cloud documentation, linked from this skill.
  2. The user's own project, read with the user's own credentials.
  3. Files and output that the user provides, such as an OpenAPI document, an error response, or a pasted log entry.

Scope

This skill covers only Google Cloud API Gateway. If the question is about Apigee, Cloud Endpoints, or GKE Gateway API, reply that this skill covers only Google Cloud API Gateway, and don't run its steps or commands.

Usage Attribution

MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.

Ground rules

| Rule | Why | | :--- | :--- | | Stay read-only until the user approves a change. While you diagnose, run only list, describe, get-iam-policy, and logging read commands, plus nslookup and curl GET requests to a path that's safe to call. | Gateways serve production traffic, and the quota metrics and limits of the most recently created API config apply to every gateway of the API. | | Before any change, show the exact command, what it changes, and how to undo it, then wait for an explicit yes. Changes include IAM grants, api-configs create, gateways update, Cloud Run ingress changes, and gcloud services enable. | The user owns the project and the change. | | Never fix a 401 or 403 by making a backend public (--allow-unauthenticated, --no-invoker-iam-check, allUsers) or by granting a basic role such as Editor. | Grant the gateway's service account the invoker role on the one backend instead, which keeps least privilege. | | Keep every log read bounded: filter on the gateway, set --freshness or a timestamp window, and set --limit. | Unbounded reads are slow and pull in caller data that the diagnosis doesn't need. | | Redact API keys, bearer tokens, and JWTs before you show log entries, commands, or files. | Request logs and pasted output can contain credentials. | | Base every limit, default, and error meaning on a linked public doc or on output from the user's project. If neither explains the problem, say so and escalate. | Guessing about undocumented behavior leads to wrong fixes. | | Use the user's existing gcloud login. Never ask for passwords, API key values, or service account key files. | Credentials don't belong in a chat transcript. | | For Preview features (streaming, MCP, model routing), check the release notes before answering. | Preview behavior changes between releases. |

Prerequisites

  1. Google Cloud CLI. Use a recent gcloud (the commands here were checked with version 591.0.0); see Install the gcloud CLI. Don't install or update software without the user's approval. If gcloud isn't available or the user says not to run commands, work in evidence mode: give the user the read-only commands to run, and diagnose from the output, response bodies, and log entries they paste.
  2. Authentication. Use the user's existing gcloud auth login session; this skill doesn't need application-default credentials.
  3. Project. Ask which project hosts the gateway and pass --project={project_id} on every command. Don't run gcloud config set, because it changes the user's environment. This skill troubleshoots existing gateways and never creates projects.
  4. Billing. The project needs an active billing account even when usage stays in the free tier; see API Gateway pricing.
  5. APIs. API Gateway requires apigateway.googleapis.com, servicemanagement.googleapis.com, and servicecontrol.googleapis.com. A gateway can keep responding while one of them is missing, and its logs then stay empty, so check with gcloud services list --enabled --project={project_id}. Enabling a missing API is a change that needs approval.
  6. IAM roles for diagnosis (read-only): roles/apigateway.viewer, roles/logging.viewer, roles/serviceusage.serviceUsageViewer, and roles/iam.serviceAccountViewer (to check the gateway's service account). For Cloud Run backends, add roles/run.viewer; to trace a custom domain through its load balancer, add roles/compute.viewer; to check an API key's project, roles/serviceusage.serviceUsageViewer is also needed there.
  7. IAM roles for fixes (only after approval): roles/apigateway.admin; roles/iam.serviceAccountUser on the gateway's service account, because creating or updating an API config or a gateway requires iam.serviceAccounts.actAs; roles/run.admin to change a Cloud Run service's IAM policy or ingress; roles/serviceusage.serviceUsageAdmin to enable an API or a managed service, plus roles/servicemanagement.serviceConsumer on the API's managed service to enable it in another project; and roles/iam.serviceAccountAdmin to re-enable a disabled service account.
  8. Region. Gateways are regional. Use the region that gateways list reports. When a fix needs a new gateway, create it in the original gateway's region, or in us-central1 if the user has no preference; see API Gateway deployment model and Cloud locations.

Workflow

Copy this checklist into your notes and tick it off as you go:

- [ ] 1. Context collected
- [ ] 2. Gateway identified by defaultHostname
- [ ] 3. Expected or transient states ruled out
- [ ] 4. Gateway log entry read (bounded query)
- [ ] 5. One branch chosen from the classification table
- [ ] 6. Root cause stated with redacted evidence and a doc link
- [ ] 7. Fix proposed, approved, and applied (or handed to the user)
- [ ] 8. Fix verified
- [ ] 9. Escalated, if the evidence points to Google Cloud

1. Collect context

Extract these from the conversation first, and ask only for what's missing:

| Needed | Why | | :--- | :--- | | {project_id} of the gateway | Every command is scoped to it. | | Failing URL (host and path) or {gateway_id} and {region} | Identifies the gateway. | | HTTP method, status code, and response body | Separates gateway errors from backend errors. | | Approximate time of the failure, in UTC | Bounds the log query. | | What changed recently (new API config, IAM, backend deploy, DNS) | Recent changes are the first place to look. | | Authentication used by the caller (API key, JWT, none) | Selects the auth branch. |

If the project or the host is unknown, stop and ask before you run any gcloud command. Don't guess project IDs, and don't use the active gcloud project instead.

2. Identify the gateway

List the project's gateways:

gcloud api-gateway gateways list --project={project_id} \
  --format="table(name.basename():label=GATEWAY,name.segment(3):label=REGION,defaultHostname,state,apiConfig)"

Match the request host against defaultHostname. Don't decide from the URL suffix: a gateway's hostname can use either of two gateway.dev formats or, for older streaming and model-routing gateways, a run.app format. Don't guess the owning project from numbers in the hostname either; list the gateways in the project the user names. A custom domain points at a load balancer whose serverless NEG targets the gateway. See references/triage-and-logs.md for the hostname formats and how to trace a custom domain.

If no gateway in the project matches, confirm the product before going on (see Scope).

Then read the gateway's details, including its API config and streaming mode:

gcloud api-gateway gateways describe {gateway_id} \
  --location={region} --project={project_id}

3. Rule out expected and transient states

  • Gateway state isn't ACTIVE: CREATING or UPDATING means an operation is still running, so wait and check again. FAILED means creation failed; read the error of the failed operation. DELETING means the gateway is being removed.
  • API config just created: creating a complex API config can take up to ten minutes, and only one config can be created for an API at a time.
  • First requests after an idle period: API Gateway has cold-start latency.
  • Google Cloud incident: check the Service Health dashboard.

4. Read the gateway log entry

Use a bounded query that prints only the fields you need. Replace {status_code} with the status the caller saw:

gcloud logging read 'resource.type="apigateway.googleapis.com/Gateway" AND resource.labels.gateway_id="{gateway_id}" AND resource.labels.location="{region}" AND httpRequest.status={status_code}' \
  --project={project_id} --freshness=1h --limit=20 \
  --format="json(timestamp,httpRequest.status,httpRequest.latency,httpRequest.requestUrl,jsonPayload.responseDetails,jsonPayload.apiConfig,jsonPayload.apiMethod)"

If you know the failure time, replace --freshness with a timestamp>="{start_utc}" AND timestamp<="{end_utc}" filter that spans about 30 minutes around it. Read httpRequest.status, httpRequest.requestUrl, jsonPayload.responseDetails, jsonPayload.apiConfig, and jsonPayload.apiMethod. Keep the --format field list, because a full entry can contain the caller's credentials, and redact credentials before you quote any field, including a key query parameter in httpRequest.requestUrl.

To compare API configs, compare only the apis/{api_id}/configs/{config_id} part: the same config can appear as a full resource name (//apigateway.googleapis.com/projects/...) and with either the project number or the project ID.

jsonPayload.responseDetails decides the branch: via_upstream means the backend produced the response; any other value means the gateway produced it. The troubleshooting page explains via_upstream and service_control_quota_error, and the model routing page explains the model_router_* values that model-routing gateways log. Quote any other value as-is, and don't explain how the gateway works internally.

5. Classify and follow one branch

Pick the first row that matches, and load only the reference file it names.

| What you see | Likely cause | Reference | | :--- | :--- | :--- | | 401 or 403 with via_upstream | The backend rejected the gateway: invoker role, audience, or deleted service account | auth-errors.md | | A 4xx produced by the gateway whose body names a credential problem (for example UNAUTHENTICATED) | The API key or JWT was rejected; quote the body | [auth-errors.md](references/auth-errors.

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars20.3k
CategoryOperations
Updated1mo ago
Forks1.7k

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
api-gateway-troubleshooting — Universal Skill: Install & Safety Check | SkillAgent