/application-integration-troubleshooting

name: application-integration-troubleshooting
metadata:
  version: "1.0.0"
  category: ApplicationDevelopment
description: >-
  Diagnoses failed, stuck, or silent Google Cloud Application Integration runs and
  Integration Connectors tasks using the REST API, Cloud Logging, and Cloud Monitoring.
  Use when an integration fails, returns HTTP 200 without doing the expected work, hangs
  in a suspended or retry state, or hits IAM, run-as service account, connector health,
  or quota errors. Do not use for initial region provisioning (use
  application-integration-basics) or building and deploying versions (use application-integration-authoring).

Application Integration Troubleshooting

Diagnose and recover Google Cloud Application Integration executions that fail, stall, or appear to do nothing. This skill walks through execution state verification, per-task failure inspection, Cloud Logging and Cloud Monitoring checks, Integration Connectors health probes, suspension resolution, and IAM or quota checks.

Tooling and Scope Boundaries

• **REST is the interface.** There is no `gcloud integrations` command group and no Google-managed MCP server for Application Integration. Use `curl` with `gcloud auth print-access-token`, or the discovery-based Python client (`googleapiclient.discovery.build("integrations", "v1")` and `build("connectors", "v1")`; install with `pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"`).
• **Generic `gcloud` commands apply** for authentication (`gcloud auth`), enabling APIs (`gcloud services`), IAM checks (`gcloud projects get-iam-policy`, `gcloud iam service-accounts get-iam-policy`), and log queries (`gcloud logging read`).
• **Regional scope.** Integrations, executions, connections, and execution logs live in a single Google Cloud region (`LOCATION`, for example `us-central1`). Querying the wrong region returns empty results.
• **Sibling skills:**
• Use `application-integration-basics` for product concepts, enabling APIs, provisioning a region, initial IAM roles, and service limits.
• Use `application-integration-authoring` for creating drafts, editing tasks and triggers, config variables, publishing, `:execute` and `:schedule` payloads, and CI/CD export/import.

Safety and Confirmation Rules

• **Read-only checks run freely:** `executions.list`, `suspensions.list`, `connections.get`, `connectionSchemaMetadata` get calls, runtime v2 `actions.list` / `entityTypes.list`, `gcloud logging read`, and `v2` `executions:troubleshoot`.
• **State-changing actions require explicit user confirmation.** Before canceling or replaying an execution, lifting or resolving a suspension, refreshing connector schema metadata, repairing connector eventing, publishing or unpublishing a version, or changing IAM bindings, show the exact command and wait for user approval.
• **Never bundle destructive scripts** or delete integrations, versions, connections, or auth profiles during troubleshooting unless the user specifically asks.

Prerequisites and Setup Check

Before querying APIs, confirm the environment has credentials, active APIs, and the right target region:

# Verify active identity and project
gcloud config get-value account
gcloud config get-value project

# Check that required APIs are enabled on PROJECT_ID
gcloud services list --enabled --project="PROJECT_ID" \
  --filter="config.name:(integrations.googleapis.com OR connectors.googleapis.com OR secretmanager.googleapis.com)"

• If an API is missing, ask the user before running `gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com --project="PROJECT_ID"`.
• Ensure an active billing account is attached to `PROJECT_ID` (required even when usage stays within the monthly free tier; see the [Application Integration pricing page](https://cloud.google.com/application-integration/pricing)).
• For Python discovery clients (install with `pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"`) or ADK (`ApplicationIntegrationToolset`), authenticate with `gcloud auth application-default login` and `gcloud auth application-default set-quota-project PROJECT_ID`.

Diagnostic Decision Flow

Follow these steps in order whenever a user reports that an integration failed, did nothing, or is stuck.

Step 1: Confirm Whether an Execution Ran and Check Its True State

Do not rely on an HTTP 200 status from `:execute` as proof that every task succeeded (note: `integrations:test` also exists in the v1 REST API, but its required `TestIntegrationsRequest.clientId` value is not publicly documented, so do not invent one; test by publishing to a non-production project and calling `:execute`). As a diagnostic rule, always check the response payload and execution record because:

• The required verification is the execution record from `executions.list?filter=execution_id="EXECUTION_ID"`—inspect `executionDetails.state`, each task's `taskExecutionState`, and `ErrorInfo` in `responseParameters` (do not rely on the legacy/deprecated `executionFailed` field, which is not a supported public signal).
• If the caller passed `"doNotPropagateError": true` on `:execute`, the API returns HTTP 200 with an `executionId` and places error details inside event parameters instead of returning an HTTP error.
• A duplicate `requestId` on `:execute` or `:schedule` returns the previous execution's response without running a new execution.
• Task failure policies (`IGNORE` and `NONE`) allow an integration to continue or finish as `SUCCEEDED` down an alternate branch even when an individual task failed.

List executions for the integration (use `-` as `INTEGRATION_NAME` to search across all integrations in the region; the discovery doc does not specify whether `orderBy=create_time` sorts ascending or descending, so add a `CreateTimestamp` filter or paginate with `pageToken` if needed):

curl -sS -H "Authorization: Bearer $(gcloud auth