Terraform, AWS Cloudfront and CNAMEAlreadyExists error

When you create a distribution, AWS creates several DNS A records with the same name (e.g. d25gma2ea3ckma.cloudfront.net) which point to IPs the distribution is using. Then, typically, you would define CNAME(s) pointing to that cloudfront.net address in your own DNS. Each Cloudfront distribution has a list of aliases, similar to Subject Alternative Names (“SAN”) in SSL certificates. The aliases should match the CNAME(s) you’ve set in DNS.

Now, this is all good until you need to migrate those Cloudfront distributions to, say, a new AWS account. If you attempt to create a new distribution (here with Terraform) with the same alias you will get this error:

aws_cloudfront_distribution.example: Creating...
╷
│ Error: error creating CloudFront Distribution: CNAMEAlreadyExists: One
| or more aliases specified for the distribution includes an incorrectly
| configured DNS record that points to another CloudFront distribution.
| You must update the DNS record to correct the problem. For more
| information, see
| https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions
│       status code: 409, request id: 4eeaa2ee-b317-4c64-a221-e09244192add
│ 
│   with aws_cloudfront_distribution.example,
│   on cloudfront.tf line 7, in resource "aws_cloudfront_distribution"
|   "example":
│    7: resource "aws_cloudfront_distribution" "example" {

The error message is very clear. Naturally you assume it tells you the whole truth, so you inform everyone that the CloudFront distribution will be down briefly while DNS propagates to AWS DNS. You wait. And you wait some more. After many hours you loose hope, because everybody’s DNS seems to have propagated, but AWS just keeps telling Terraform the same thing. And finally you give up and restore the old CNAME and go back to the drawing board.

The problem here turns out to be simple: the error message does not tell the whole truth. In fact, based on experimentation, it is not enough to remove the CNAME. It is also not enough to disable the old Cloudfront distribution - you really need to delete it first. It may be enough to change the aliases in the old distribution so that they no longer overlap with the new distribution you’re creating, but that was not tested - SSL might make that process more complicated than expected.