Amazon AppStream 2.0 Diagnostics
When to use
Any Amazon AppStream 2.0 investigation where the console alone is insufficient — fleet management, image building, streaming sessions, user authentication, VPC networking, application configuration, or storage troubleshooting.
Investigation workflow
Step 1 — Collect and triage
aws appstream describe-fleets --names <fleet-name>
aws appstream describe-stacks --names <stack-name>
aws appstream describe-image-builders --names <builder-name>
aws appstream describe-images --names <image-name>
Step 2 — Domain deep dive
aws appstream describe-sessions --stack-name <stack> --fleet-name <fleet>
aws appstream describe-users --authentication-type USERPOOL
aws cloudwatch get-metric-statistics --namespace AWS/AppStream --metric-name ActualCapacity --dimensions Name=Fleet,Value=<fleet> --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/AppStream --metric-name InsufficientCapacityError --dimensions Name=Fleet,Value=<fleet> --start-time <start> --end-time <end> --period 300 --statistics Sum
Step 3 — Detailed investigation
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=appstream.amazonaws.com --max-results 20
aws s3 ls s3://<home-folder-bucket>/<user-prefix>/
aws appstream describe-fleet-metadata --fleet-name <fleet-name>
Read references/appstream-guardrails.md before concluding on any AppStream issue.
Tool quick reference
| Tool / API |
When to use |
describe-fleets |
Check fleet status, capacity, configuration |
describe-stacks |
Check stack configuration and associations |
describe-image-builders |
Check image builder status |
describe-images |
Check image status and applications |
describe-sessions |
Check active streaming sessions |
describe-users |
Check user pool users |
| CloudWatch Metrics |
Monitor capacity, sessions, errors |
| CloudTrail |
Audit API calls and configuration changes |
| S3 |
Check home folders and app settings |
Gotchas: Amazon AppStream 2.0
- Fleet instances are NOT EC2 instances you manage directly. You cannot SSH into them, install software on running fleet instances, or modify them. Use image builders to create custom images with your applications.
- Image builder is for creating custom images. Connect to the image builder via the AppStream console, install applications, create the image, then use it with fleets. Image builders are temporary — delete after creating the image.
- Always-on vs on-demand fleet types: always-on instances are running and ready (faster session start, higher cost). On-demand instances start when users connect (slower start, lower cost). Choose based on user experience vs cost requirements.
- Streaming protocol is NICE DCV. It requires specific network ports (443 for HTTPS, UDP 8433 for streaming). Firewalls and proxies must allow these ports. WebSocket connections are used for the streaming session.
- User pool vs SAML: AppStream user pool is built-in user management. SAML federation integrates with external identity providers (Okta, Azure AD, etc.). They cannot be mixed on the same stack.
- Home folders use S3. Each user gets a home folder backed by an S3 bucket. The bucket is created automatically. Users can save files that persist across sessions. Home folder size affects S3 costs.
- App settings persistence uses S3. Application settings (browser bookmarks, IDE preferences) are saved to S3 and restored in new sessions. This requires enabling app settings persistence on the stack.
- Fleet auto-scaling is based on capacity utilization. Scaling policies use CloudWatch metrics. Configure minimum, maximum, and desired capacity. Scaling cooldown periods prevent rapid scaling oscillation.
- Session timeout vs disconnect timeout: idle disconnect timeout disconnects idle users. Disconnect timeout determines how long a disconnected session is preserved before termination. Max session duration limits total session length.
Anti-hallucination rules
- Always cite specific fleet names, image names, session IDs, or API responses as evidence.
- Fleet instances are NOT directly manageable EC2 instances. Never suggest SSH or direct instance modification.
- Image builders are for image creation only. Never suggest using image builders for production streaming.
- NICE DCV is the streaming protocol. Never suggest RDP or other protocols.
- Home folders and app settings use S3. Never suggest EBS or EFS for AppStream storage.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
20 runbooks
| Category |
IDs |
Covers |
| A — Fleet |
A1–A3 |
Fleet creation, scaling, instance failures |
| B — Image |
B1–B2 |
Image builder, image creation |
| C — Streaming |
C1–C3 |
Session failures, latency, disconnects |
| D — User |
D1–D2 |
User pool, SAML federation |
| E — Networking |
E1–E2 |
VPC config, internet access |
| F — Application |
F1–F2 |
App launch failures, app settings persistence |
| G — Storage |
G1–G2 |
Home folders, app settings |
| Z — Catch-All |
Z1 |
General troubleshooting |
1---2name: appstream-diagnostics3description: Use this skill to investigate and troubleshoot Amazon AppStream 2.0 problems by analyzing fleet creation, scaling issues, instance failures, image builder configuration, image creation, streaming session failures, latency, disconnects, user pool management, SAML federation, VPC configuration, internet access, application launch failures, app settings persistence, home folders, app settings storage, and following structured runbooks. Activate when: fleet creation failures, scaling not working, instance failures, image builder issues, image creation errors, streaming session failures, high latency, frequent disconnects, user pool problems, SAML federation errors, VPC configuration issues, internet access problems, application launch failures, app settings not persisting, home folder issues, storage problems, or the user says something is wrong with AppStream without naming specific symptoms.4---56# Amazon AppStream 2.0 Diagnostics78## When to use910Any Amazon AppStream 2.0 investigation where the console alone is insufficient — fleet management, image building, streaming sessions, user authentication, VPC networking, application configuration, or storage troubleshooting.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws appstream describe-fleets --names <fleet-name>18aws appstream describe-stacks --names <stack-name>19aws appstream describe-image-builders --names <builder-name>20aws appstream describe-images --names <image-name>21```2223### Step 2 — Domain deep dive2425```26aws appstream describe-sessions --stack-name <stack> --fleet-name <fleet>27aws appstream describe-users --authentication-type USERPOOL28aws cloudwatch get-metric-statistics --namespace AWS/AppStream --metric-name ActualCapacity --dimensions Name=Fleet,Value=<fleet> --start-time <start> --end-time <end> --period 300 --statistics Average29aws cloudwatch get-metric-statistics --namespace AWS/AppStream --metric-name InsufficientCapacityError --dimensions Name=Fleet,Value=<fleet> --start-time <start> --end-time <end> --period 300 --statistics Sum30```3132### Step 3 — Detailed investigation3334```35aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=appstream.amazonaws.com --max-results 2036aws s3 ls s3://<home-folder-bucket>/<user-prefix>/37aws appstream describe-fleet-metadata --fleet-name <fleet-name>38```3940Read `references/appstream-guardrails.md` before concluding on any AppStream issue.4142## Tool quick reference4344| Tool / API | When to use |45|------------|-------------|46| `describe-fleets` | Check fleet status, capacity, configuration |47| `describe-stacks` | Check stack configuration and associations |48| `describe-image-builders` | Check image builder status |49| `describe-images` | Check image status and applications |50| `describe-sessions` | Check active streaming sessions |51| `describe-users` | Check user pool users |52| CloudWatch Metrics | Monitor capacity, sessions, errors |53| CloudTrail | Audit API calls and configuration changes |54| S3 | Check home folders and app settings |5556## Gotchas: Amazon AppStream 2.05758- Fleet instances are NOT EC2 instances you manage directly. You cannot SSH into them, install software on running fleet instances, or modify them. Use image builders to create custom images with your applications.59- Image builder is for creating custom images. Connect to the image builder via the AppStream console, install applications, create the image, then use it with fleets. Image builders are temporary — delete after creating the image.60- Always-on vs on-demand fleet types: always-on instances are running and ready (faster session start, higher cost). On-demand instances start when users connect (slower start, lower cost). Choose based on user experience vs cost requirements.61- Streaming protocol is NICE DCV. It requires specific network ports (443 for HTTPS, UDP 8433 for streaming). Firewalls and proxies must allow these ports. WebSocket connections are used for the streaming session.62- User pool vs SAML: AppStream user pool is built-in user management. SAML federation integrates with external identity providers (Okta, Azure AD, etc.). They cannot be mixed on the same stack.63- Home folders use S3. Each user gets a home folder backed by an S3 bucket. The bucket is created automatically. Users can save files that persist across sessions. Home folder size affects S3 costs.64- App settings persistence uses S3. Application settings (browser bookmarks, IDE preferences) are saved to S3 and restored in new sessions. This requires enabling app settings persistence on the stack.65- Fleet auto-scaling is based on capacity utilization. Scaling policies use CloudWatch metrics. Configure minimum, maximum, and desired capacity. Scaling cooldown periods prevent rapid scaling oscillation.66- Session timeout vs disconnect timeout: idle disconnect timeout disconnects idle users. Disconnect timeout determines how long a disconnected session is preserved before termination. Max session duration limits total session length.6768## Anti-hallucination rules69701. Always cite specific fleet names, image names, session IDs, or API responses as evidence.712. Fleet instances are NOT directly manageable EC2 instances. Never suggest SSH or direct instance modification.723. Image builders are for image creation only. Never suggest using image builders for production streaming.734. NICE DCV is the streaming protocol. Never suggest RDP or other protocols.745. Home folders and app settings use S3. Never suggest EBS or EFS for AppStream storage.756. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.7677## 20 runbooks7879| Category | IDs | Covers |80|----------|-----|--------|81| A — Fleet | A1–A3 | Fleet creation, scaling, instance failures |82| B — Image | B1–B2 | Image builder, image creation |83| C — Streaming | C1–C3 | Session failures, latency, disconnects |84| D — User | D1–D2 | User pool, SAML federation |85| E — Networking | E1–E2 | VPC config, internet access |86| F — Application | F1–F2 | App launch failures, app settings persistence |87| G — Storage | G1–G2 | Home folders, app settings |88| Z — Catch-All | Z1 | General troubleshooting |
aws-samples