Skip to main content

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.

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.