Troubleshooting domains

There are many common reasons why your domain configuration may not be working. Check the following:

When you add a domain to Vercel that you have purchased from a third-party DNS provider, you may see an Invalid Configuration alert. There are many reasons why this could be the case:

• You need to configure the DNS records of your domain with your DNS provider so they can be used with your project. To resolve this, follow the steps to configure your domain.
• If your domain is in use by another Vercel account, you may be prompted to verify access to the domain by adding a TXT record. This will not move the domain into your account, but will allow you to use it in your project.
• There was an issue generating the SSL certificate for your domain. The most common reason for this is missing CAA records. For information on other issues that may cause this, see the common SSL certificate issues section.
• You have configured wildcard subdomains on your project, but their nameservers aren’t with Vercel. When using a wildcard domain, you must use the nameservers method.

Vercel is expecting DNS records of either 76.76.21.21 (for A record) or cname.vercel-dns.com (for CNAME record). Use the following commands on your Terminal to check the DNS records are correctly configured:

• dig ns [domain] to get a domain’s nameservers
• dig a [apex domain e.g. example.com] to get a domain’s A record
• dig cname [subdomain e.g. www.example.com] to get a domain’s CNAME record

If you prefer a non-command-line interface, you can use a free online tool, such as Google Public DNS. If any of these results do not match what is expected, follow the steps to configure your domain.

DNS changes can take a while to propagate across the globe, depending on the previous DNS record TTL length. This may mean that certain regions can access your site as intended, while others wait until the DNS changes have reached them. Please allow some time for these changes to take effect.

For more information on propagation times for nameservers and other DNS records, see "How long will it take for my Vercel DNS records to update?"

While we allow the creation of AAAA records when using Vercel's nameservers, we do not support IPv6 yet. This means if you are adding a custom domain from a third-party, you won't be able to point an AAAA record to Vercel.

When working with DNS records, you may make minor errors in the syntax. These errors can be difficult to debug. Below is a list of common errors made when adding DNS records and the steps required to resolve them.

When you add a new DNS record to a domain, the Name field should use the prefix or location of the record. For www.example.com, the name argument would be www.

If you have already added a record with this, remove the record from the DNS Records section of the Domains tab, and add the record again without the domain as the Name argument.

When you add a custom domain with a subdomain to your project, we'll prompt you to add a CNAME DNS record in order to configure the domain. This record includes a period (.) at the end of the Value field. This is intentional to denote that it is an absolute, fully qualified domain name.

This means that when you add a new CNAME record to your DNS provider, you must copy the value exactly as it appears, including the period.

When you add any custom domain to your Vercel project you must configure the DNS records with your DNS provider so it can be used with your project. When you add a wildcard domain (such as *.example.com), you must use the Nameservers method.

This is because Vercel needs to be able to set DNS records in order to generate the wildcard certificates. The service that Vercel uses to generate the certificates requires us to verify the domain ownership by using the DNS-01 challenge method. By changing the nameservers, Vercel will handle the DNS-01 challenge for you automatically, and you don't need to update your verification DNS record upon your certificate renewal each time.

For more information, see Why must we use the Domain Nameservers method for Wildcard Domains on Vercel?

When you buy a new domain, you may want to also set up an email address with this domain. Vercel does not provide a mail service for domains purchased with or transferred into it. To learn how to set up email, see How do I send and receive emails with my Vercel purchased domain?

When you add your custom domain to a project and use Vercel's nameservers, you will need to add MX records to continue receiving email. To learn how to add MX records, see Why am I no longer receiving email after adding my domain to Vercel?

All domain purchases and renewals through Vercel are final and cannot be refunded once processed. For more information, see Can I get a refund for a domain purchased or renewed with Vercel?

It can take 3-5 days for a domain to fully register. If the domain is still not showing after 5 days, you can contact support.

You will need to convert the domain to punycode in order to add it to your project. For example, a user looking to add a domain such as jérémie.fr can do so in the form of xn--jrmie-bsab.fr.

ICANN forces domain registrars to wait 60 days:

• between transfers
• between a new registration and a subsequent transfer

If you transfer before this time, the transfer will fail. Besides this restriction, some DNS providers may further restrict domain transferring by default as a security measure, unless the owner explicitly turns off their protection setting. Please refer to the DNS provider's documentation for more details.

When you add an apex domain (e.g. example.com) to your project, Vercel provides you with details, including an IP address, to add as an A record in your DNS configuration, as opposed to a CNAME record.

The main reason for that is the DNS RFC1034 (section 3.6.2) states that If a CNAME RR is present at a node, no other data should be present. Because an apex domain requires NS records and usually some other records, such as MX (for a mail service), adding a CNAME at the zone apex would violate this rule and likely cause an issue on your domain. Therefore, we encourage you to use an A record at your zone apex instead.

When you configure an apex domain (example.com) as a custom domain for your project on Vercel, Vercel will be give you an IP address to add as an A record in your DNS configuration. Although this IP address resolves to a specific geographic location, it does not mean that when your users point to your domain, they will be sent to this specific geographic location to resolve the domain.

This is because Vercel uses Anycast IP addresses, which are shared across all regions. That means even if your users access your domain resolving to the same IP addresses from different geographic locations, they will be routed to the closest Edge Network location relative to your users, based on the BGP (Border Gateway Protocol).

When you add a domain to your project, Vercel checks if it is already associated with a Personal Account or Team. A domain can only be associated with one Personal Account or Team at a time.

The following table shows errors that can be encountered when adding a domain to your project:

There are many reasons why a certificate may not be generated. As the first starting point, we recommend testing your domain with:

1. Let's Debug: Let's Debug is a diagnostic tool/website to help figure out why you might not be able to issue a certificate for Let's Encrypt
2. DNSViz: DNSViz is a tool suite for analysis and visualization of Domain Name System (DNS) behavior, including its security extensions (DNSSEC). They can also tell you about possible DNS misconfiguration.

For non-wildcard domains, we use HTTP-01 challenge by default, which Vercel handles automatically by intercepting the challenge requests from Let's Encrypt to your domain as long as the domain points to Vercel.

For wildcard domains, only DNS-01 challenge is supported, which Vercel requires you to use the nameservers method to handle DNS-01 challenge requests with Vercel's nameservers automatically.

Since we use Let's Encrypt for our automatic SSL certificates, you must add a CAA record with the value 0 issue "letsencrypt.org" if other CAA records already exist on your domain.

You can check if your domain currently has any CAA records by running the dig -t CAA +noall +ans example.com command on your terminal, or check with Google Public DNS (change the RR Type to CAA and resolve).

For more information, see Why is my domain not automatically generating an SSL certificate?

An _acme-challenge record allows Let's Encrypt to verify the domain ownership using DNS-01 challenge. This may exist on your apex or subdomains, so can be checked with dig -t TXT _acme-challenge.example.com or dig -t TXT _acme-challenge.subdomain.example.com

If the domain was previously hosted on a different provider, and if the _acme-challenge record resolves to something, please consider removing the DNS record. This will prevent any provider (other than the one in the DNS record) from provisioning certificates for that domain.

The /.well-known path is reserved and cannot be redirected or rewritten. Only Enterprise teams can configure custom SSL. Contact sales to learn more.