api-gateway-troubleshooting
Diagnoses failing requests and deployment errors on Google Cloud API Gateway
Install / Use
npx skills add google/skills --skill api-gateway-troubleshootingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| api-gateway-troubleshooting (this skill)by google | 95 | 20.3k | 54d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
| crawl4aiby unclecode | 100 | 87.4k | 3d ago | MCP 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.
Skill content
View source on GitHubname: 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:
- Public Google Cloud documentation, linked from this skill.
- The user's own project, read with the user's own credentials.
- 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
- 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. Ifgcloudisn'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. - Authentication. Use the user's existing
gcloud auth loginsession; this skill doesn't need application-default credentials. - Project. Ask which project hosts the gateway and pass
--project={project_id}on every command. Don't rungcloud config set, because it changes the user's environment. This skill troubleshoots existing gateways and never creates projects. - Billing. The project needs an active billing account even when usage stays in the free tier; see API Gateway pricing.
- APIs. API Gateway requires
apigateway.googleapis.com,servicemanagement.googleapis.com, andservicecontrol.googleapis.com. A gateway can keep responding while one of them is missing, and its logs then stay empty, so check withgcloud services list --enabled --project={project_id}. Enabling a missing API is a change that needs approval. - IAM roles for diagnosis (read-only):
roles/apigateway.viewer,roles/logging.viewer,roles/serviceusage.serviceUsageViewer, androles/iam.serviceAccountViewer(to check the gateway's service account). For Cloud Run backends, addroles/run.viewer; to trace a custom domain through its load balancer, addroles/compute.viewer; to check an API key's project,roles/serviceusage.serviceUsageVieweris also needed there. - IAM roles for fixes (only after approval):
roles/apigateway.admin;roles/iam.serviceAccountUseron the gateway's service account, because creating or updating an API config or a gateway requiresiam.serviceAccounts.actAs;roles/run.adminto change a Cloud Run service's IAM policy or ingress;roles/serviceusage.serviceUsageAdminto enable an API or a managed service, plusroles/servicemanagement.serviceConsumeron the API's managed service to enable it in another project; androles/iam.serviceAccountAdminto re-enable a disabled service account. - Region. Gateways are regional. Use the region that
gateways listreports. When a fix needs a new gateway, create it in the original gateway's region, or inus-central1if 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
stateisn'tACTIVE:CREATINGorUPDATINGmeans an operation is still running, so wait and check again.FAILEDmeans creation failed; read the error of the failed operation.DELETINGmeans 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
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.4kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
