Troubleshooting

This article covers issues you may run into during SaaS onboarding and during ongoing SaaS scans. For Cloud Scanner-specific runtime issues that apply to both SaaS and Outpost, see also the Cloud Scanner troubleshooting guide.

Common onboarding issues

Preflight script reports missing permissions

Symptom: The upwindctl aws onboarding preflight command in Step 2 reports one or more permission failures.

Likely cause: The identity running the preflight script does not have the AWS permissions described in the Prerequisites, or a Service Control Policy (SCP) blocks the action.

How to fix:

1. Re-run aws sso login --profile <management-profile> to make sure your terminal session is using the correct AWS identity.
2. Inspect the exact action the preflight script could not perform, and verify the identity has the corresponding iam:*, organizations:*, or other permission.
3. If your AWS Organization enforces SCPs, confirm the SCPs allow the failing action for the relevant account.
4. Re-run the preflight script. Proceed to Step 3 only once it passes.

Invalid role ARN at the validation step

Symptom: Pasting the OrganizationServiceRoleArn into the Enter role ARN field and clicking Validate returns an error.

Likely causes:

• The CloudFormation stack from Step 3.2 is still being created.
• The wrong ARN was copied (for example, an inner role created by the nested stack rather than the OrganizationServiceRoleArn output).
• The trust policy on the role does not match the expected Upwind SaaS account ID and external ID (typically because the stack was edited after creation).

How to fix:

1. Wait for the CloudFormation stack to reach CREATE_COMPLETE. For larger AWS Organizations this can take several minutes.
2. Open the stack's Outputs tab and copy the value labelled OrganizationServiceRoleArn exactly.
3. If the stack completed but validation still fails, redeploy the stack with the Run the AWS CloudFormation template link in the onboarding center. Because the stack's parameters (including the Upwind SaaS trusted account ID and external ID) are pre-populated by Upwind, redeploying regenerates the trust policy with the correct values.

Validation error messages

When you click Validate, Upwind runs a series of checks against the role and your AWS Organization. If a check fails, one of the following messages is shown. Use the table below to identify the cause and the corrective action.

Error message	What it means	How to fix
Role ARN is invalid. The provided role ARN format is incorrect.	The value entered in the Enter role ARN field is not a well-formed ARN.	Copy the OrganizationServiceRoleArn value exactly from the stack's Outputs tab, with no leading or trailing spaces.
Role access validation failed. Upwind was unable to assume the provided role.	The role exists but Upwind could not assume it, usually because of a trust policy mismatch.	Confirm the stack reached CREATE_COMPLETE, then redeploy with the Run the AWS CloudFormation template link so the trust policy is regenerated with the correct Upwind account ID and external ID.
IAM configuration validation failed. The required Upwind IAM tags were not found on the role.	The role is missing the IAM tags Upwind expects.	Redeploy the CloudFormation stack from the Upwind Console so the role is recreated with the required tags. Avoid editing the role's tags manually.
Orchestrator account validation failed. The orchestrator account defined in the IAM configuration does not exist within the connected AWS Organization.	The orchestrator account referenced by the role is not a member of the AWS Organization you are connecting.	Verify you are validating from the correct management account, and that the orchestrator account belongs to the same AWS Organization.
AWS Organization validation failed. The AWS Organization ID does not match the one provided.	The role belongs to a different AWS Organization than the one selected in Upwind.	Make sure the role was deployed in the management account of the AWS Organization you intend to connect, then re-run validation.
Discovery permissions validation failed. Upwind does not have sufficient permissions to list accounts or organizational units.	The role lacks the organizations:* permissions needed to discover accounts and organizational units.	Redeploy the CloudFormation stack to restore the role's permissions, and confirm no Service Control Policy (SCP) blocks the organizations:List* actions.

Terraform: apply to every account in scope

Unlike the CloudFormation template, the Terraform module is not automatically deployed across your accounts - it must be applied to each account in your selected scope. If accounts are missing or member accounts cannot be discovered, confirm the module was applied from the Management Account, and applied within every account in scope - including the management and orchestrator accounts - then re-run Validate.

CloudFormation deployment fails

Symptom: The CloudFormation stack hits CREATE_FAILED or ROLLBACK_COMPLETE.

Likely causes:

• A previous attempt left behind IAM roles with names that conflict with the new attempt. Delete the leftover resources, then redeploy.
• SCPs block creation of the IAM roles defined in the template. Inspect the failed event in CloudFormation; the error will name the action and resource.

How to fix:

1. Open the failed stack in the AWS CloudFormation console and review Events for the first failed action.
2. Resolve the root cause (delete conflicting role, adjust SCP, enable the region).
3. Delete the failed stack and re-run the Run the AWS CloudFormation template link from the onboarding center.