AWSAmplifyDomainRole Cannot Be Found: A Quick Fix

You are deploying with AWS Amplify, and a build fails with something like: The role with name AWSAmplifyDomainRole-Z073737928BZTN2WA6J6L cannot be found. The long suffix is different for everyone, but the cause is usually the same.

This tends to show up when you are using Amplify Hosting with a custom domain. Below is a plain-English explanation of what the role does and how to recreate it so your deployments work again.

Understanding the "AWSAmplifyDomainRole Cannot Be Found" Error

So, what is this AWSAmplifyDomainRole and why does it sometimes disappear?

When you add a custom domain to your Amplify application, Amplify creates an IAM (Identity and Access Management) role. This role, named AWSAmplifyDomainRole-…, grants Amplify the necessary permissions to manage resources related to your domain, such as SSL/TLS certificates through AWS Certificate Manager (ACM).

The error occurs because this essential IAM role has been deleted, but Amplify's configuration still expects it to exist. This can happen for several reasons:

• Manual Deletion: Someone on your team might have inadvertently deleted the role from the IAM console, perhaps during a cleanup of unused roles.
• Automated Scripts: Cleanup scripts designed to remove unused AWS resources might accidentally target and delete this role.
• Domain Reconfiguration: Sometimes, removing and re-adding a custom domain in a specific sequence can leave the configuration in an inconsistent state, leading to the role being deleted while the reference to it remains.

Regardless of the cause, the outcome is a failed deployment because Amplify can no longer find the role it needs to manage your domain.

The Solution: Re-creating the IAM Role

Since the role is missing, the most direct solution is to create it again with the correct permissions. The process involves creating a new IAM role and attaching a specific trust policy that allows Amplify to assume it.

While this issue has been discussed by the community and is tracked in a GitHub issue here↗ (opens in a new tab), you don't have to wait for a patch. You can resolve it yourself in just a few minutes by following the steps below.

Step-by-Step Guide to Creating the AWSAmplifyDomainRole

Let's walk through creating the necessary IAM role. Make sure you are logged into your AWS Console before you begin.

Step 1: Navigate to the IAM Console

First, go to the IAM service in your AWS Console. You can find it by typing "IAM" into the main search bar and selecting it from the results.

Step 2: Create a New Role

In the IAM dashboard, click on "Roles" in the left-hand navigation pane. Then, click the "Create role" button.

Step 3: Select Trust Entity

This is the key step. You need to tell AWS which service is allowed to use this role.

1. For the trusted entity type, select "Custom trust policy".
2. A JSON editor will appear. Replace the default content with the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "amplify.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

This policy explicitly grants the AWS Amplify service (amplify.amazonaws.com) permission to assume this role.

After pasting the policy, click "Next".

Step 4: Add Permissions (Optional but Recommended)

On the "Add permissions" page, you don't strictly need to attach any policies for this specific fix. The trust relationship is the key part. However, Amplify uses this role to manage certificates. If you continue to face issues, you can attach the AWS managed policy AWSCertificateManagerFullAccess to be safe, though it's often not required as Amplify manages this.

For this guide, we will skip adding extra permissions as the trust policy is sufficient to resolve the error. Click "Next".

Step 5: Name the Role and Finalize

Now, you will name the role. This is another key detail. The name must match exactly.

1. For the "Role name", enter the exact name shown in your error message, such as AWSAmplifyDomainRole-Z073737928BZTN2WA6J6L.
2. You can add an optional description, such as "Role for AWS Amplify to manage custom domain resources and SSL certificates."
3. Review the details to ensure the trusted entity is amplify.amazonaws.com and the role name is correct.
4. Click the "Create role" button.

You should see a success message confirming that the role has been created.

Step 6: Retry Your Amplify Deployment

With the AWSAmplifyDomainRole now back in place, return to your AWS Amplify console and restart the build or deployment that previously failed. Amplify will now be able to find the required role and proceed with the domain management tasks, resolving the error.

A More Permanent Fix: Prevent Accidental Deletion

Creating the role again is a quick fix, but how do you prevent this from happening in the future?

1. Educate Your Team: Make sure everyone on your team who has IAM access understands the importance of the AWSAmplifyDomainRole. Advise against deleting IAM roles unless they are certain they are no longer in use.
2. Tag Your Resources: Apply tags to the AWSAmplifyDomainRole (e.g., Project: MyApp, ManagedBy: Amplify). This adds context and can help prevent accidental deletion by people or automated scripts.
3. Refine Cleanup Scripts: If you use scripts to clean up unused AWS resources, add an exception for roles with the name AWSAmplifyDomainRole or roles tagged as managed by Amplify.

Conclusion

Running into the AWSAmplifyDomainRole cannot be found error is a common snag when using custom domains with AWS Amplify. The fix is straightforward: recreate the missing IAM role with the right trust policy.

Once the role exists again, rerun your Amplify build and it should move past the domain step.

Meta Information

Meta Title: Fix: AWSAmplifyDomainRole Cannot Be Found in AWS Amplify
Meta Description: Getting the "AWSAmplifyDomainRole cannot be found" error? Our step-by-step guide shows you how to fix this AWS Amplify issue and get your deployment running.