Appsync Diagnostics

AppSync Diagnostics

When to use

Any AppSync investigation where the console alone is insufficient — resolver errors, schema deployment failures, authorization issues, subscription connection problems, caching misconfigurations, query latency, N+1 data fetching, or merged API conflicts.

Investigation workflow

Step 1 — Collect and triage

aws appsync list-graphql-apis
aws appsync get-graphql-api --api-id 
aws appsync list-resolvers --api-id  --type-name 
aws appsync list-data-sources --api-id 
aws appsync get-schema-creation-status --api-id 
aws appsync list-api-keys --api-id 

Step 2 — Domain deep dive

aws appsync get-resolver --api-id  --type-name  --field-name 
aws appsync get-data-source --api-id  --name 
aws cloudwatch get-metric-statistics --namespace AWS/AppSync --metric-name 4XXError --dimensions Name=GraphQLAPIId,Value= ...
aws cloudwatch get-metric-statistics --namespace AWS/AppSync --metric-name 5XXError --dimensions Name=GraphQLAPIId,Value= ...
aws cloudwatch get-metric-statistics --namespace AWS/AppSync --metric-name Latency --dimensions Name=GraphQLAPIId,Value= ...
aws appsync list-functions --api-id 

Read references/appsync-guardrails.md before concluding on any AppSync issue.

Tool quick reference

| Tool / API | When to use | |------------|-------------| | list-graphql-apis | List all APIs in the account/region | | get-graphql-api | API config, auth modes, log settings, endpoints | | list-resolvers | Resolvers for a given type | | get-resolver | Resolver runtime, mapping templates, pipeline config | | list-data-sources | All data sources attached to the API | | get-data-source | Data source type, config, IAM role | | get-schema-creation-status | Schema deployment status and errors | | list-api-keys | API key expiration and status | | list-functions | Pipeline functions for pipeline resolvers |

Gotchas: AppSync

• VTL mapping templates (Apache Velocity) vs JavaScript resolvers (APPSYNC_JS runtime) are two distinct resolver runtimes. VTL uses $ctx and $util, JavaScript uses ctx and util — they are NOT interchangeable.
• Pipeline resolvers chain multiple functions (before → function1 → function2 → ... → after). Each function has its own request/response mapping. The $ctx.stash (VTL) or ctx.stash (JS) passes data between functions.
• Resolver timeout is 30 seconds maximum. This cannot be increased. For long-running operations, use async patterns with DynamoDB or EventBridge.
• Subscriptions connect via WebSocket using the wss:// endpoint (realtime endpoint). The connection URL is different from the GraphQL HTTP endpoint. Clients must use graphql-ws or Amplify libraries.
• Real-time subscriptions use MQTT over WebSocket protocol internally. Connection limits apply: 100 subscriptions per connection, connection idle timeout of 5 minutes without keepalive.
• Five authorization modes: APIKEY, AMAZONCOGNITOUSERPOOLS, AWSIAM, OPENIDCONNECT, AWS_LAMBDA. Multiple auth modes can be configured on a single API with @aws_auth directives.
• Caching TTL is configurable per API (1–3600 seconds). Per-resolver caching overrides API-level caching. Caching requires a dedicated cache instance (t2.small to r5.12xlarge) — it is NOT free.
• Conflict detection for offline/real-time sync: Versioned (optimistic concurrency), Automerge (automatic conflict resolution), Lambda (custom resolution logic). Only applies when using AppSync with DataStore/Amplify.
• Merged APIs combine multiple source APIs into a single endpoint. Schema conflicts between source APIs cause merge failures. Source API changes require re-merge.
• Batch resolvers (BatchInvoke for Lambda, BatchGetItem for DynamoDB) solve the N+1 problem. Without batching, a list query with N items triggers N individual resolver invocations.

Authorization mode comparison

| Mode | Use Case | Token Location | Expiry | |------|----------|---------------|--------| | API_KEY | Public/dev access | x-api-key header | Max 365 days | | COGNITO | User-based auth | Authorization header (JWT) | Token-based | | IAM | Service-to-service | SigV4 signed request | Session-based | | OIDC | External IdP | Authorization header (JWT) | Token-based | | LAMBDA | Custom auth logic | Custom token header | Per-request |

Anti-hallucination rules

1. Always cite specific API configurations, resolver code, CloudWatch metrics, or error messages as evidence.
2. VTL and JavaScript resolvers have completely different syntax and utilities. Never mix VTL $util with JavaScript util or vice versa.
3. Resolver timeout is hard-capped at 30 seconds. Never suggest increasing it beyond 30s.
4. Subscription endpoints use wss:// and are different from the GraphQL HTTPS endpoint. Never use the HTTP endpoint for subscriptions.
5. Caching requires a provisioned cache instance with associated costs. Never claim caching is free or automatic.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

26 runbooks

| Category | IDs | Covers | |----------|-----|--------| | A — API | A1–A3 | API creation failures, schema errors, deployment issues | | B — Resolvers | B1–B4 | VTL errors, JavaScript resolver errors, pipeline failures, timeout | | C — Data Sources | C1–C4 | DynamoDB, Lambda, HTTP, RDS/Aurora data source errors | | D — Auth | D1–D3 | API key issues, Cognito auth, IAM/OIDC auth | | E — Subscriptions | E1–E2 | WebSocket connection failures, subscription filtering | | F — Caching | F1–F2 | Cache configuration, cache invalidation | | G — Performance | G1–G2 | Query latency, N+1 resolver issues | | Z — Catch-All | Z1 | General troubleshooting |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aws-samples
• Source: aws-samples/sample-ai-agent-skills
• License: MIT-0

Install and usage instructions live in the source repository linked above.