---

name: gcp-troubleshoot description: "Troubleshoot GCP services using tool-first access (via MCP when available), falling back to the CLI only when necessary. Focus on Firestore, Cloud Run, networking, load balancers, IAM, Pub/Sub, Cloud SQL, and Storage."

GCP Troubleshooting Skill

General Guidance

Always attempt to investigate issues using tool-based access first (MCP tools if configured).
Only fall back to the GCP CLI (gcloud) when the tool cannot access required logs, metrics, or audit data.

All investigations should:

1. Scope queries by service/resource type
2. Restrict by time window
3. Prefer targeted logs/metrics, not full dumps
4. Diagnose root cause based on error type
5. Suggest minimal, safe remediation steps

---

Core Services Covered

Firestore

Common issues:

• PERMISSION_DENIED
• Missing indexes
• Transaction contention
• Quota exceeded

Investigations:

• Query Firestore logs filtered by resource.type="firestore_database"
• Check latency, retries, aborted transactions

Cloud Run

Common issues:

• Startup failures
• Crash loops
• IAM failures calling other services
• Cold starts

Investigations:

• Query Cloud Run logs (resource.type="cloud_run_revision")
• Check revision rollout history
• Look for Cloud SQL connector errors or storage access failures

Networking & Load Balancers

Common issues:

• 5xx responses
• Backend connection errors
• Firewall denies

Investigations:

• Query load balancer logs (resource.type="http_load_balancer")
• Inspect backend health logs
• Check VPC routes + firewall rules

IAM

Common issues:

• PermissionDenied
• Missing service account roles

Investigations:

• Query audit logs: protoPayload.status.code != 0
• Identify the principal, resource, and role mismatch

Pub/Sub

Common issues:

• Failed push deliveries
• Ack deadlines exceeded
• DLQ accumulation

Investigations:

• Filter subscription logs
• Inspect subscriber errors and endpoint failures

Cloud SQL

Common issues:

• Connection limit reached
• Auth failures
• Private network routing failures

Investigations:

• Cloud SQL logs (resource.type="cloudsql_database")
• Check database flags, failover events, connection counts

Storage Buckets

Common issues:

• 403 Forbidden
• Precondition checks
• Signed URL failures

Investigations:

• Inspect Storage logs (resource.type="gcs_bucket")
• Check IAM, bucket policies, object existence

---

Workflow

1. Identify target resource
2. Query scoped logs
3. Query metrics
4. Query audit logs if access or permission failures occur
5. Interpret patterns
6. Suggest actionable fixes

---

When to Warn

• Unscoped log queries
• Very wide time ranges
• Requests requiring IAM escalation