short answer
The DNS record types of NETLIFY and NETLIFYv6 are special “alias” records within Netlify DNS. They will return the IP addresses for the closest CDN nodes based on the IP address of the system making the DNS lookup.
dns_api example.com- example.com 400 - link exists, all config must be empty
Are you seeing an error like this one?
This happens when you try to create an A or AAAA type DNS record and there is a conflicting NETLIFY or NETLIFYv6 type record.
Before you can create the A or AAAA record, you must first delete NETLIFY or NETLIFYv6 record. Once the NETLIFY types are deleted the A or AAAA record can be created and no error will occur.
Note, it is the NETLIFY type record which points that name to Netlify. If you delete the NETLIFY (and NETLIFYv6) type records, it will take the site offline at Netlify.
However, in most cases you are creating the A record precisely to move domain to some other service. If so, deleting the NETLIFY type record is the correct step before making the A record.
two important facts about NETLIFY and NETLIFYv6 type records
- These records only connect domain names to IP addresses.
- These records do not control which site the domain name is linked to (if any).
Note, you will only have NETLIFYv6 records if you enabled IPv6 support for your domain - something which is optional. Going forward in this guide, I’m going to just call them “NETLIFY type records” but, when I write this, I mean both “NETLIFY and NETLIFYv6 type records”.
#1: these records only connect the domain names to IP addresses
The records will return an IPv4 IP address for NETLIFY type records and IPv6 address for NETLIFYv6 records.
Many different IP addresses will be returned if repeated requests are made and this is normal. The different IP addresses point to different CDN nodes. Almost all locations will have multiple CDN nodes handling requests for that geographic area. So you can, will, and should get more then one IP address if you make repeated lookups for the same NETLIFY type record.
#2: these records don’t control the site shown
The record value will show the name of the first site the domain is linked to. This value doesn’t change if domain name is moved to a new site or if the original site is deleted.
The DNS record values don’t update currently because they don’t technically need to. The value doesn’t control anything related to the site and is cosmetic only. However, there is a feature request to change this behavior as this is a frequent source of confusion.
Even if you delete the domain from all sites, the NETLIFY type records will still exist. Also, if you move a domain name to a new site, the value will show the original site. It will show the original site name regardless of how many times you move it or, again, even if the original site is deleted entirely. You can move the domain to a new site and the NETLIFY record will still show the first site it was added to, a site which might not even exist anymore. (There is a feature request to automatically change the record when name is moved to a different site.)
So, why doesn’t the value update? That answer is because of point two above - these records do not control which site is shown. The hostname shown in the web UI never appears in the DNS responses. Historically, these records were not updated because it wasn’t strictly necessary. Again, the domain name in the value isn’t returned in the DNS response. That value is purely cosmetic and is actually never used in any way.
How do I change the name in the NETLIFY type DNS records?
If you really want to change the name in the record the workflow to do so is this:
- Remove the domain name(s) you want to change from the site’s custom domain settings (under Site Name > Settings > Domain management > Custom domains).
- Delete the NETLIFY (and possibly the NETLIFYv6) type record(s) you want to change from the DNS zone.
- Add the domain name(s) back to the site’s custom domain setting.
Note, this will take the site will be offline from step 1 until step 3 is completed.
Again, though, no one but you (or other team members) will ever see that value in the NETLIFY UI and if you don’t change it things will still work correctly. You can leave it as is safely if you prefer.
What does control which site is shown for a domain name?
Finally, I want to answer a question some of you might have, which is:
- What does control which site is shown for a domain name?
The setting which controls the site shown for a specific domain name is in the site settings, not the DNS settings. It is the setting: Site Name > Settings > Domain management > Custom domains. This is known as the “custom domain” setting for the site.
So, for a domain to point to a site, there are two requirements:
- The domain name must point to an IP address at Netlify (which is what these NETLIFY records do).
- The domain name must be added as a “custom domain” under the site settings.
The site shown for a domain name is controlled completely by the site custom domain setting and not the DNS records. Again, the DNS records point to IP addresses and nothing else.
Summary
I hope this clarifies the (admittedly confusing) details about the NETLIFY type DNS records. The DNS records only point to IP addresses that Netlify uses for our CDN. It is the site setting that controls what site we show for a domain, not the DNS records.
UPDATE: These records used to be locked and required assistance from our support team to unlock. However, this changed in January of 2021. You can now delete these records at any time without needing to request them to be unlocked.