How do I troubleshoot errors when I create a custom domain in Amazon Cognito?

Short description

When configuring custom domain names in Amazon Cognito, the following errors commonly occur:

• "Custom domain is not a valid subdomain: Was not able to resolve the root domain, please ensure an A record exists for the root domain."
• "Domain already associated with another user pool."
• "One or more of the CNAMEs you provided are already associated with a different resource."
• "The specified SSL certificate doesn't exist, isn't in us-east-1 region, isn't valid, or doesn't include a valid certificate chain."
• "The domain name contains an invalid character. Domain names can only contain lower-case letters, numbers, and hyphens. Please enter a different name that follows this format: ^a-z0-9?$"

Resolution

Custom domain is not a valid subdomain error

To prevent accidental changes to infrastructure, Amazon Cognito doesn't support top-level domains (TLDs) for custom domains. To create an Amazon Cognito custom domain, the parent domain must have a Domain Name System (DNS) A record.

The parent might be either the root of the domain or a child domain that's one step up in the domain hierarchy. For example, if your custom domain is auth.xyz.yourdomain.com, then Amazon Cognito must resolve **xyz.**yourdomain.com to an IP address. Similarly, to configure xyz.yourdomain.com as a custom domain, configure an A record for yourdomain.com.

You must create an A record for the parent domain in your DNS configuration. When the parent domain resolves to a valid A record, Amazon Cognito doesn't perform additional verifications. If the parent domain doesn't point to a real IP address, then consider putting a dummy IP address, such as "8.8.8.8", in your DNS configuration.

Your DNS provider might take time to propagate the changes that you made to your DNS configuration. To make sure that your DNS provider propagated the change, run one of the following commands.

Using auth.xyz.yourdomain.com as the custom domain:

$ dig A xyz.yourdomain.com +short

-or-

Using xyz.yourdomain.com as the custom domain:

$ dig A yourdomain.com +short

Note: The preceding example commands are for a Linux environment.

If the DNS configuration change propagates, then the previous command returns the IP address that you configured. If the DNS lookup isn't returning the configured IP address, then wait until the change is propagated. Otherwise, you keep getting the "custom domain is not a valid subdomain" error.

After the custom domain is created in Amazon Cognito, you can remove the parent domain A record mapping you configured earlier.

Domain already associated with another user pool error

Custom domain names must be unique across all AWS accounts in all AWS Regions. When you use a custom domain name for a user pool, the same domain name can't be used for any other user pool. You must delete the custom domain associated with the first user pool if you want to use the domain name for another user pool.

After deleting a custom domain, it takes time to fully dissociate the custom domain from the user pool. If you try to configure the domain name with another user pool immediately after deletion, then you might encounter the domain association error. If you receive the domain association error, then wait 15-20 minutes before setting up the domain name with the new user pool.

One or more of the CNAMEs you provided are already associated with a different resource error

After creating a custom domain, Amazon Cognito creates an AWS managed Amazon CloudFront distribution using the same custom domain name. You can use a domain name with only one CloudFront distribution. If you're using a domain name as an alternate domain in CloudFront, then you can't use the existing domain name to create a custom domain. If you try to create a custom domain that's already associated with a CloudFront distribution, then the CNAME association error appears.

You can resolve this error in one of the following two ways:

• Use a different domain name for the Amazon Cognito custom domain.
• When using the domain as an Amazon Cognito custom domain, stop using the domain name with another CloudFront distribution.

The specified SSL certificate doesn't exist error

1. To create an Amazon Cognito custom domain, you must have an AWS Certificate Manager (ACM) certificate in the us-east-1 AWS Region. When you create the custom domain, Amazon Cognito internally creates a CloudFront distribution. CloudFront supports ACM certificates only in the us-east-1 Region.
2. When you configure the custom domain, make sure that the certificate you select isn't expired.
3. If you import a certificate into ACM, then make sure that the certificate is issued by a public certificate authority (CA). The certificate must also have the correct certificate chain. For more information, see Importing certificates into AWS Certificate Manager.
4. Your certificate must be 2,048 bits or smaller in size. The certificate can't be password protected.
5. If an AWS Key Management Service (AWS KMS) policy evaluation results in an explicit deny statement, then you might receive an SSL certificate error. When certain AWS KMS actions are explicitly denied for the IAM user or role that creates the Amazon Cognito custom domain, this error occurs. The error most commonly occurs for the following explicitly denied AWS KMS actions: kms:DescribeKey, kms:CreateGrant, or kms:*.

The domain name contains an invalid character error

If a domain name contains anything other than lowercase letters, numbers, and hyphens, then the domain name isn't accepted. You can't use a hyphen for the first or last character. The maximum length of the whole domain name, including the dots, is 63 characters.

---

Related information

Using your own domain for the hosted UI