WorkSpaces Diagnostics
When to use
Any WorkSpaces investigation where the console alone is insufficient — launch failures, client connectivity issues, streaming protocol problems, MFA configuration, performance degradation, directory integration errors, VPC networking, rebuild/restore operations, or security configuration.
Investigation workflow
Step 1 — Collect and triage
aws workspaces describe-workspaces --workspace-id <id>
aws workspaces describe-workspace-directories
aws workspaces describe-workspace-bundles --bundle-ids <id>
aws ds describe-directories
aws cloudwatch get-metric-statistics --namespace AWS/WorkSpaces --metric-name Available --dimensions Name=WorkspaceId,Value=<id> --start-time <iso> --end-time <iso> --period 300 --statistics Average
Step 2 — Domain deep dive
aws workspaces describe-workspace-images
aws workspaces describe-connection-status --workspace-id <id>
aws workspaces describe-workspace-snapshots --workspace-id <id>
aws ds describe-conditional-forwarders --directory-id <id>
aws ec2 describe-security-groups --group-ids <sg-id>
aws ec2 describe-subnets --subnet-ids <subnet-id>
Read references/guardrails.md before concluding on any WorkSpaces issue.
Tool quick reference
| Tool / API |
When to use |
workspaces describe-workspaces |
WorkSpace state, bundle, directory, IP |
workspaces describe-workspace-directories |
Directory registration, subnets, security |
workspaces describe-workspace-bundles |
Bundle config, compute type, storage |
workspaces describe-connection-status |
Last known client connection state |
workspaces describe-workspace-images |
Custom image status and errors |
ds describe-directories |
Directory type, status, DNS, VPC |
ds describe-conditional-forwarders |
DNS forwarding to on-premises AD |
ec2 describe-security-groups |
Security group rules for WorkSpaces |
ec2 describe-subnets |
Subnet CIDR, AZ, available IPs |
Gotchas: WorkSpaces
- WorkSpaces require at least two subnets in different AZs for directory registration, even if you only launch in one AZ.
- The WorkSpaces client uses port 4172 (TCP and UDP) for PCoIP and port 4195 (TCP and UDP) for WSP. Both must be open in security groups and NACLs.
- WorkSpaces have a 20-minute health check interval. A WorkSpace showing UNHEALTHY may recover on the next check cycle.
- Custom bundles created from a WorkSpace inherit the source WorkSpace's volume sizes. You cannot reduce volume size after creation.
- MFA with AD Connector requires a RADIUS server. AWS Managed Microsoft AD supports smart card and RADIUS-based MFA.
- WorkSpaces in ADMIN_MAINTENANCE state cannot be accessed by users. This state is used for patching and updates.
- Rebuilding a WorkSpace restores the root volume from the latest bundle image and the user volume from the last snapshot.
- WorkSpaces auto-stop mode stops the WorkSpace after a configurable idle timeout (default 1 hour). Users must reconnect to restart.
- IP access control groups are allowlists. If configured, only IPs in the group can connect. An empty group blocks all connections.
- WorkSpaces Web Access requires WSP protocol. PCoIP does not support browser-based access.
Anti-hallucination rules
- Always cite specific WorkSpace state, connection status, directory configuration, or CloudWatch metrics as evidence.
- UNHEALTHY state does not mean the WorkSpace is permanently broken. Always check if it recovers on the next health check.
- Never claim PCoIP supports Web Access. Only WSP protocol supports browser-based connections.
- WorkSpaces require two subnets in different AZs. Never suggest single-subnet directory registration.
- Rebuilding preserves user volume data from the last snapshot, not real-time data. Never claim rebuild preserves all current user data.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
22 runbooks
| Category |
IDs |
Covers |
| A — Provisioning |
A1–A3 |
Launch failures, bundle issues, directory integration |
| B — Connectivity |
B1–B3 |
Client connection, streaming protocol, MFA |
| C — Performance |
C1–C2 |
Latency, bandwidth |
| D — Directory |
D1–D2 |
AD Connector, AWS Managed AD |
| E — Networking |
E1–E2 |
VPC config, internet access |
| F — Management |
F1–F2 |
Rebuild, restore, maintenance |
| G — Security |
G1–G2 |
Encryption, access control |
| Z — Catch-All |
Z1 |
General troubleshooting |
1---2name: workspaces-diagnostics3description: Use this skill to investigate and troubleshoot Amazon WorkSpaces problems by analyzing provisioning, connectivity, performance, directory integration, networking, management operations, and security configurations following structured runbooks. Activate when: WorkSpace launch failures, bundle issues, directory integration problems, client connection failures, streaming protocol issues, MFA failures, latency or bandwidth problems, AD Connector or AWS Managed AD issues, VPC configuration errors, internet access problems, rebuild/restore failures, maintenance window issues, encryption problems, access control issues, or the user says something is wrong with WorkSpaces without naming specific symptoms.4---56# WorkSpaces Diagnostics78## When to use910Any WorkSpaces investigation where the console alone is insufficient — launch failures, client connectivity issues, streaming protocol problems, MFA configuration, performance degradation, directory integration errors, VPC networking, rebuild/restore operations, or security configuration.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws workspaces describe-workspaces --workspace-id <id>18aws workspaces describe-workspace-directories19aws workspaces describe-workspace-bundles --bundle-ids <id>20aws ds describe-directories21aws cloudwatch get-metric-statistics --namespace AWS/WorkSpaces --metric-name Available --dimensions Name=WorkspaceId,Value=<id> --start-time <iso> --end-time <iso> --period 300 --statistics Average22```2324### Step 2 — Domain deep dive2526```27aws workspaces describe-workspace-images28aws workspaces describe-connection-status --workspace-id <id>29aws workspaces describe-workspace-snapshots --workspace-id <id>30aws ds describe-conditional-forwarders --directory-id <id>31aws ec2 describe-security-groups --group-ids <sg-id>32aws ec2 describe-subnets --subnet-ids <subnet-id>33```3435Read `references/guardrails.md` before concluding on any WorkSpaces issue.3637## Tool quick reference3839| Tool / API | When to use |40|------------|-------------|41| `workspaces describe-workspaces` | WorkSpace state, bundle, directory, IP |42| `workspaces describe-workspace-directories` | Directory registration, subnets, security |43| `workspaces describe-workspace-bundles` | Bundle config, compute type, storage |44| `workspaces describe-connection-status` | Last known client connection state |45| `workspaces describe-workspace-images` | Custom image status and errors |46| `ds describe-directories` | Directory type, status, DNS, VPC |47| `ds describe-conditional-forwarders` | DNS forwarding to on-premises AD |48| `ec2 describe-security-groups` | Security group rules for WorkSpaces |49| `ec2 describe-subnets` | Subnet CIDR, AZ, available IPs |5051## Gotchas: WorkSpaces5253- WorkSpaces require at least two subnets in different AZs for directory registration, even if you only launch in one AZ.54- The WorkSpaces client uses port 4172 (TCP and UDP) for PCoIP and port 4195 (TCP and UDP) for WSP. Both must be open in security groups and NACLs.55- WorkSpaces have a 20-minute health check interval. A WorkSpace showing UNHEALTHY may recover on the next check cycle.56- Custom bundles created from a WorkSpace inherit the source WorkSpace's volume sizes. You cannot reduce volume size after creation.57- MFA with AD Connector requires a RADIUS server. AWS Managed Microsoft AD supports smart card and RADIUS-based MFA.58- WorkSpaces in ADMIN_MAINTENANCE state cannot be accessed by users. This state is used for patching and updates.59- Rebuilding a WorkSpace restores the root volume from the latest bundle image and the user volume from the last snapshot.60- WorkSpaces auto-stop mode stops the WorkSpace after a configurable idle timeout (default 1 hour). Users must reconnect to restart.61- IP access control groups are allowlists. If configured, only IPs in the group can connect. An empty group blocks all connections.62- WorkSpaces Web Access requires WSP protocol. PCoIP does not support browser-based access.6364## Anti-hallucination rules65661. Always cite specific WorkSpace state, connection status, directory configuration, or CloudWatch metrics as evidence.672. UNHEALTHY state does not mean the WorkSpace is permanently broken. Always check if it recovers on the next health check.683. Never claim PCoIP supports Web Access. Only WSP protocol supports browser-based connections.694. WorkSpaces require two subnets in different AZs. Never suggest single-subnet directory registration.705. Rebuilding preserves user volume data from the last snapshot, not real-time data. Never claim rebuild preserves all current user data.716. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.7273## 22 runbooks7475| Category | IDs | Covers |76|----------|-----|--------|77| A — Provisioning | A1–A3 | Launch failures, bundle issues, directory integration |78| B — Connectivity | B1–B3 | Client connection, streaming protocol, MFA |79| C — Performance | C1–C2 | Latency, bandwidth |80| D — Directory | D1–D2 | AD Connector, AWS Managed AD |81| E — Networking | E1–E2 | VPC config, internet access |82| F — Management | F1–F2 | Rebuild, restore, maintenance |83| G — Security | G1–G2 | Encryption, access control |84| Z — Catch-All | Z1 | General troubleshooting |
aws-samples