AWS Security ChangesHomeSearch

AWS wellarchitected: Reformat troubleshooting causes list and labels

Service: wellarchitected · 2026-11-06 · Documentation low

File: wellarchitected/latest/userguide/agent-troubleshooting.md

Summary

Editorial/formatting-only change: replaces the repeated '**Possible causes and solutions:**' lead-in with 'Check the following possible causes and solutions:' and changes bold cause labels from a trailing colon to an en-dash. One minor wording fix ('in your profile details page' -> 'on your profile details page'). No substantive content, guidance, or security information is added or removed.

Security assessment

The diff only alters list formatting and punctuation (colon to en-dash, reworded lead-in sentence). The IAM/SCP/sts:AssumeRole text is pre-existing and merely re-punctuated, so no new security guidance, vulnerability fix, or exposure change is introduced.

Evidence

+Check the following possible causes and solutions:

Diff

diff --git a/wellarchitected/latest/userguide/agent-troubleshooting.md b/wellarchitected/latest/userguide/agent-troubleshooting.md
index 5bfecf1..d71ad65 100644
--- a//wellarchitected/latest/userguide/agent-troubleshooting.md
+++ b//wellarchitected/latest/userguide/agent-troubleshooting.md
@@ -17 +17 @@ This section provides solutions to common issues you may encounter when setting
-**Possible causes and solutions:**
+Check the following possible causes and solutions:
@@ -19 +19 @@ This section provides solutions to common issues you may encounter when setting
-  * **Missing application context:** At least one application context is required per profile. Navigate to **Profile Details** , choose the **Application context** tab, and add an application.
+  * **Missing application context** – At least one application context is required per profile. Navigate to **Profile Details** , choose the **Application context** tab, and add an application.
@@ -21 +21 @@ This section provides solutions to common issues you may encounter when setting
-  * **No pillars selected:** Your profile must have at least one optimization pillar. Edit the profile and select one or more pillars.
+  * **No pillars selected** – Your profile must have at least one optimization pillar. Edit the profile and select one or more pillars.
@@ -25 +25 @@ This section provides solutions to common issues you may encounter when setting
-  * **Execution role does not exist or lacks permissions:** Verify the execution role ARN in your profile details page exists in IAM and has a permissions policy allowing `sts:AssumeRole` on your access roles.
+  * **Execution role does not exist or lacks permissions** – Verify the execution role ARN on your profile details page exists in IAM and has a permissions policy allowing `sts:AssumeRole` on your access roles.
@@ -27 +27 @@ This section provides solutions to common issues you may encounter when setting
-  * **No accounts configured:** Your aggregation configuration must include at least one account. Edit the profile and add accounts to monitor.
+  * **No accounts configured** – Your aggregation configuration must include at least one account. Edit the profile and add accounts to monitor.
@@ -36 +36 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-**Possible causes and solutions:**
+Check the following possible causes and solutions:
@@ -38 +38 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Missing service-role/ path prefix:** If you created the execution role using the **Create new role** button in the AWS WA Agent console, the role is placed under the `service-role/` path. Use `arn:aws:iam::`111122223333`:role/service-role/ExecutionRoleForWellArchitectedAgent`, not `arn:aws:iam::`111122223333`:role/ExecutionRoleForWellArchitectedAgent`. Confirm the exact ARN from your profile details page.
+  * **Missing service-role/ path prefix** – If you created the execution role using the **Create new role** button in the AWS WA Agent console, the role is placed under the `service-role/` path. Use `arn:aws:iam::`111122223333`:role/service-role/ExecutionRoleForWellArchitectedAgent`, not `arn:aws:iam::`111122223333`:role/ExecutionRoleForWellArchitectedAgent`. Confirm the exact ARN from your profile details page.
@@ -40 +40 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Wrong account ID in trust policy:** The Principal ARN must reference the account where your AWS WA Agent profile is created (the profile-owning account), not the workload account.
+  * **Wrong account ID in trust policy** – The Principal ARN must reference the account where your AWS WA Agent profile is created (the profile-owning account), not the workload account.
@@ -42 +42 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Trust policy not applied to all accounts:** Each workload account in your aggregation configuration needs its own access role with the trust policy. Verify every account listed in your profile has a correctly configured access role.
+  * **Trust policy not applied to all accounts** – Each workload account in your aggregation configuration needs its own access role with the trust policy. Verify every account listed in your profile has a correctly configured access role.
@@ -44 +44 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Execution role missing`sts:AssumeRole` permission:** The execution role in your profile account must have a permissions policy that allows `sts:AssumeRole` on your access roles. Verify the execution role's permissions policy includes an `sts:AssumeRole` action with the access role ARNs as resources. If you created the execution role through the AWS WA Agent console, the permissions policy must specify an access role name (for example, `AccessRoleForWellArchitectedAgent`) and cannot use wildcard (`*`) resources.
+  * **Execution role missing`sts:AssumeRole` permission** – The execution role in your profile account must have a permissions policy that allows `sts:AssumeRole` on your access roles. Verify the execution role's permissions policy includes an `sts:AssumeRole` action with the access role ARNs as resources. If you created the execution role through the AWS WA Agent console, the permissions policy must specify an access role name (for example, `AccessRoleForWellArchitectedAgent`) and cannot use wildcard (`*`) resources.
@@ -51 +51 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-**Possible causes and solutions:**
+Check the following possible causes and solutions:
@@ -53 +53 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Profile not eligible:** Call `GetAgentProfile` and confirm `eligibleForScheduledGeneration` is `true`. If `false`, resolve the `fieldErrors` first.
+  * **Profile not eligible** – Call `GetAgentProfile` and confirm `eligibleForScheduledGeneration` is `true`. If `false`, resolve the `fieldErrors` first.
@@ -55 +55 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Missing application context:** At least one application context is required. Check the **Application context** tab in your profile details.
+  * **Missing application context** – At least one application context is required. Check the **Application context** tab in your profile details.
@@ -57 +57 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Access role permissions insufficient:** Verify the [`WellArchitectedAgentResourceScanning`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/WellArchitectedAgentResourceScanning.html) managed policy is attached to each access role.
+  * **Access role permissions insufficient** – Verify the [`WellArchitectedAgentResourceScanning`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/WellArchitectedAgentResourceScanning.html) managed policy is attached to each access role.
@@ -59 +59 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Recently created profile:** Scheduled recommendations can take up to 24 hours after profile setup is complete. If less than 24 hours have elapsed, wait for the next generation cycle.
+  * **Recently created profile** – Scheduled recommendations can take up to 24 hours after profile setup is complete. If less than 24 hours have elapsed, wait for the next generation cycle.
@@ -66 +66 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-**Possible causes and solutions:**
+Check the following possible causes and solutions:
@@ -75 +75 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-**Possible causes and solutions:**
+Check the following possible causes and solutions:
@@ -77 +77 @@ To identify the specific issue, call `GetAgentProfile` and check the `fieldError
-  * **Maximum profiles reached:** You have reached the maximum number of agent profiles for your support plan tier. See [AWS Well-Architected Agent Quotas and limits](./agent-quotas.html) for tier-specific limits. Delete an unused profile or upgrade your support plan tier.
+  * **Maximum profiles reached** – You have reached the maximum number of agent profiles for your support plan tier. See [AWS Well-Architected Agent Quotas and limits](./agent-quotas.html) for tier-specific limits. Delete an unused profile or upgrade your support plan tier.
@@ -86 +86 @@ If you have the correct IAM permissions but a service control policy (SCP) in AW
-**Possible causes and solutions:**
+Check the following possible causes and solutions:
@@ -88 +88 @@ If you have the correct IAM permissions but a service control policy (SCP) in AW
-  * **SCP does not allow the AWS WA Agent actions:** SCPs set the maximum available permissions for member accounts and do not grant access on their own. An SCP must allow the `wellarchitected:*` actions at every level between the member account and the organization root. Without these actions, you cannot create an agent profile. From the management account, update the applicable SCP to allow the `wellarchitected:*` namespace.
+  * **SCP does not allow the AWS WA Agent actions** – SCPs set the maximum available permissions for member accounts and do not grant access on their own. An SCP must allow the `wellarchitected:*` actions at every level between the member account and the organization root. Without these actions, you cannot create an agent profile. From the management account, update the applicable SCP to allow the `wellarchitected:*` namespace.
@@ -90 +90 @@ If you have the correct IAM permissions but a service control policy (SCP) in AW
-  * **SCP does not allow the resource-scanning actions:** The access roles use the [`WellArchitectedAgentResourceScanning`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/WellArchitectedAgentResourceScanning.html) managed policy so that AWS WA Agent can view your resources. An SCP must allow those actions at every level between the member account and the organization root. If the SCP blocks them, you can create a profile, but recommendation generation returns empty applications because AWS WA Agent cannot view your resources. From the management account, update the applicable SCP to allow those actions.
+  * **SCP does not allow the resource-scanning actions** – The access roles use the [`WellArchitectedAgentResourceScanning`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/WellArchitectedAgentResourceScanning.html) managed policy so that AWS WA Agent can view your resources. An SCP must allow those actions at every level between the member account and the organization root. If the SCP blocks them, you can create a profile, but recommendation generation returns empty applications because AWS WA Agent cannot view your resources. From the management account, update the applicable SCP to allow those actions.
@@ -92 +92 @@ If you have the correct IAM permissions but a service control policy (SCP) in AW
-  * **You cannot edit the SCP:** You manage SCPs from the organization management account. If your account is a member account, contact your management-account administrator to update the policy.
+  * **You cannot edit the SCP** – You manage SCPs from the organization management account. If your account is a member account, contact your management-account administrator to update the policy.
@@ -94 +94 @@ If you have the correct IAM permissions but a service control policy (SCP) in AW
-  * **AWS Control Tower Region-deny control:** If your organization uses AWS Control Tower, you might need to add the `wellarchitected:*` actions as an exception to the Region-deny control. Repairing drift in AWS Control Tower can remove manual SCP edits.
+  * **AWS Control Tower Region-deny control** – If your organization uses AWS Control Tower, you might need to add the `wellarchitected:*` actions as an exception to the Region-deny control. Repairing drift in AWS Control Tower can remove manual SCP edits.