Account Factory for Terraform (AFT) troubleshooting guide - AWS Control Tower

Account Factory for Terraform (AFT) troubleshooting guide

This section can help you troubleshoot common issues that you might encounter when using Account Factory for Terraform (AFT).

General issues

  • Exceeded AWS resource quotas

    If your log groups indicate that you exceeded AWS resource quotas, contact AWS Support. Account Factory uses AWS services with resource quotas that include AWS CodeBuild, AWS Organizations, and AWS Systems Manager. For more information, see the following:

  • Outdated version of Account Factory

    If you encounter an issue and believe the issue is a bug, make sure that you have the latest version of Account Factory. For more information, see Updating the Account Factory version.

  • Local changes were made to the Account Factory source code

    Account Factory is an open source project. AWS Control Tower supports the Account Factory core code. If you make a local change to the Account Factory core code, AWS Control Tower only supports your Account Factory deployment on a best-effort basis.

  • Insufficient Account Factory role permissions

    Account Factory creates IAM roles and policies to manage vended account deployments and customizations. If you change these roles or policies, the Account Factory pipeline may be unable to perform certain actions. For more information, see Required roles.

  • Account repositories not populated correctly

    Make sure that you follow the post-deployment steps before provisioning accounts.

  • Not detecting drift after changing the OU manually


    AWS Control Tower detects drift automatically. For information about resolving drift, see Detect and resolve drift in AWS Control Tower.

    Drift isn't detected when the organizational unit (OU) is changed manually. This is due to the event-driven nature of Account Factory. When an account request is submitted, the resource that Terraform manages is an Amazon DynamoDB item, not a direct account. After an item is changed, the request is put in a queue, where AWS Control Tower processes them through Service Catalog (the service that manages account details). If you change the OU manually, drift isn't detected because the account request hasn't changed.

Issues related to account provisioning/registration

  • Account request (email address/name) already exists

    The issue typically results in an Service Catalog product failure during provisioning or as ConditionalCheckFailedException.

    You can find more information about the issue by doing one of the following:

    • Review your Terraform or CloudWatch Logs log groups.

    • Review the failures that are emitted to the Amazon SNS topic aft-failure-notifications.

  • Malformed account request

    Make sure that your account request follows the expected schema. For examples, see terraform-aws-control_tower_account_factory on GitHub.

  • Exceeded AWS Organizations resource quotas

    Make sure that your account request doesn't exceed AWS Organizations resource quotas. For more information, see Quotas for AWS Organizations.

Issues related to customizations invocation

  • Target account not onboarded to Account Factory

    Make sure all accounts that are included in a customization request have been onboarded to Account Factory. For more information, see Update an existing account.

  • Account that customization request targets exists in the DynamoDB table aft-request-metadata, but not in account request repository

    Format your customization invocation request to exclude the offending account by doing one of the following:

    • In the DynamoDB table aft-request-metadata, delete the entry referencing the account that's no longer in your account request repository.

    • Not using "all" as the target.

    • Not targeting the OU that the account belongs to.

    • Not targeting the account directly.

  • Used incorrect token for Terraform Cloud

    Make sure that you set up the correct token. Terraform Cloud only supports team-based tokens, not organization-based tokens.

  • Failed to create account before account customizations pipeline is created; can't customize account

    Make a change to the account specification in the account request repository. When you make a change, such as changing a tag value for an account, Account Factory follows the path that tries to create the pipeline, even if the pipeline doesn't exist.

Issues related to the account customizations workflow

If you're experiencing issues related to the account customizations workflow, make sure that your version of AFT is 1.8.0 or higher, and that you delete all instances of account-related metadata from your DynamoDB request table.

For information about AFT version 1.8.0, see Release 1.8.0 on GitHub.

For information about how to check and update your version of AFT, see the following:

You can also trace and troubleshoot customization requests by using Amazon CloudWatch Logs Insights queries to filter logs containing your target account and customization request IDs. For more information, see Troubleshooting with AFT account customization request tracing.