Netlify Custom Domain DNS Setup

This guide is for teams publishing a static site, docs surface, or preview environment on Netlify with a custom hostname.

The first Netlify decision is not the record type. It is who remains authoritative for DNS. Netlify DNS can manage the zone and its generated records, while external DNS keeps records at the current provider and requires you to copy Netlify’s instructions there. Mixing the two dashboards is how an apparently correct record ends up in an inactive zone.

Choose Netlify DNS or external DNS

Add the custom domain in Domain management for the intended Netlify project before changing public DNS. Netlify then shows instructions tailored to the domain and selected DNS path.

Use dig NS example.com +short to confirm which provider is authoritative. A Netlify DNS zone visible in the dashboard does not answer public queries until the registrar actually delegates nameservers to it.

If DNS stays external, make every record change at the provider named by the authoritative NS answer. If the whole zone moves to Netlify DNS, inventory mail, verification, and service records before changing nameservers.

Configure an external-DNS subdomain

For a subdomain such as docs.example.com, Netlify’s standard external-DNS path is a CNAME to that project’s netlify.app hostname:

Type: CNAME
Name: docs
Value: example-site.netlify.app

Use the project hostname shown in Netlify. High-Performance Edge projects can receive a different dedicated target, so another site’s netlify.app value is not a safe substitute.

The A record versus CNAME guide explains why this subdomain flow should not be copied directly onto the zone apex.

Treat apex and www as a pair

With external DNS, Netlify handles an apex and its www variant together. Assigning either can add both domain names to the project, but each still needs the correct DNS shape:

• the www subdomain uses the project CNAME
• the apex uses an ALIAS, ANAME, or flattened CNAME to Netlify’s documented apex load balancer when the DNS provider supports one
• otherwise, use the current fallback A-record value shown by Netlify’s domain instructions and official external-DNS documentation

Choose the primary domain in Netlify so the other variant redirects intentionally. Do not leave both returning independent copies of the site with conflicting canonical URLs.

Verify authoritative DNS before certificate status

For a subdomain, query the alias directly:

dig docs.example.com CNAME +short

Expected shape:

example-site.netlify.app.

Also query the authoritative nameserver when recursive resolvers disagree. If the authoritative answer is right and public resolvers are split, follow the cache timeline in DNS Propagation: TTLs, Caches, and Verification instead of stacking a second record.

For an apex, check every record family you intentionally configured:

dig example.com A +short
dig example.com AAAA +short

An old AAAA record from a previous host can keep some clients away from Netlify and is one of the certificate and reachability failures Netlify calls out in its troubleshooting guidance.

Illustrative verification record

Illustrative example using reserved example domains and IPs.

Diagnose automatic HTTPS in Domain management

Once DNS validates, Netlify can provision HTTPS for the custom hostname.

Verify:

curl -I https://docs.example.com

Healthy output should look like a successful HTTPS response from the deployed site:

HTTP/2 200
content-type: text/html; charset=UTF-8

Header casing and exact values vary by site configuration, so focus on the status, certificate, and final content.

If the certificate remains pending, open Domain management → HTTPS and diagnose the state Netlify reports:

• DNS verification failed: confirm the project owns the domain and public DNS points to Netlify.
• Waiting on DNS propagation: look for old A, AAAA, or CNAME answers instead of repeatedly requesting a certificate.
• An external proxy or CDN terminates traffic first: Netlify’s troubleshooting guidance may require disabling that routing while Netlify validates the hostname and provisions its certificate.
• Only apex or www receives a certificate: confirm both names are assigned and both DNS shapes are correct, then use Netlify’s certificate renewal control if documented for the reported state.
• An inactive Netlify DNS zone exists: either complete nameserver delegation or remove the unused zone and keep all records at the actual authoritative provider.

Restrictive CAA policy can also block a managed certificate. Review CAA Records and Let’s Encrypt before changing unrelated application settings.

Launch checklist

Before calling the custom domain ready, confirm:

• Netlify shows the domain as configured for the intended site
• authoritative DNS is managed in the provider you intended
• apex and www have the distinct record shapes Netlify requested
• HTTPS is valid in a fresh browser session
• redirects and canonical tags use the final host
• the old preview URL is not promoted as the public address

The cleanest Netlify rollout leaves one clear chain of responsibility: one project owns the hostname, one authoritative DNS provider publishes the records, and Netlify’s HTTPS status agrees with what public clients receive.