How to Fix DNS_PROBE_FINISHED_NXDOMAIN for Websites, APIs, and Local Development

Overview

NXDOMAIN stands for non-existent domain. In practice, it means the DNS lookup for a hostname returned “this name does not exist” rather than “the server is down” or “the app is broken.” That distinction matters because an NXDOMAIN error is usually a naming or DNS configuration issue, not an application runtime issue.

You will commonly see DNS_PROBE_FINISHED_NXDOMAIN in browsers when:

• a domain or subdomain was never created
• the hostname exists in one DNS provider, but the domain is delegated to another
• you recently changed nameservers and are checking the wrong zone
• the record type is wrong, missing, or attached to the wrong host
• the resolver or browser is using stale local cache
• a local development hostname has no mapping in /etc/hosts or your local DNS service

The fastest way to troubleshoot is to separate the problem into layers:

1. Confirm the exact hostname. Is the failing name example.com, www.example.com, api.example.com, or a local alias such as app.test?
2. Check delegation. Which nameservers are authoritative for the domain right now?
3. Check the authoritative zone. Does the hostname exist there with the expected A, AAAA, or CNAME record?
4. Check propagation and caching. Are you seeing old answers from a resolver or browser?
5. Check platform-specific requirements. Hosting platforms often require exact records and hostnames.

If you are still early in the process, avoid changing multiple things at once. One of the most common reasons DNS troubleshooting drags on is that teams update nameservers, records, proxies, and app settings in parallel and then cannot tell which change fixed or broke the result.

Checklist by scenario

Use the checklist that matches your setup. Start with the scenario that is closest to the failing hostname.

1. Website or root domain is not resolving

If the main site such as example.com fails with NXDOMAIN, work through this order:

1. Verify the domain spelling. Check for missing letters, wrong TLD, accidental hyphens, or copying a preview domain instead of the real one.
2. Check whether the domain is delegated to the DNS provider you expect. The zone may exist in Cloudflare or Route 53, but if the registrar still points elsewhere, those records will not matter.
3. Open the authoritative DNS zone. Look for an A record, AAAA record, ALIAS/ANAME if your provider supports it, or the platform-specific record your host requires.
4. Confirm there is not an empty root with only a www record. A common mistake is configuring www.example.com but not example.com.
5. Check nameserver changes. If you recently changed nameservers, allow time for recursive resolvers to refresh. Use a propagation check instead of relying on one browser.
6. Test from outside your machine. Use dig or nslookup against public resolvers to compare results.

If you need a refresher on how hostnames map to A records, CNAMEs, nameservers, and TTL, see How to Point a Domain to a Server: A Record, CNAME, Nameservers, and TTL Explained.

2. Subdomain such as api.example.com is not resolving

Subdomain NXDOMAIN issues often come from host naming errors rather than full-zone failures.

1. Confirm the exact host value in your DNS provider. Many dashboards expect just api, not api.example.com. Others accept the full hostname. Entering the wrong format can silently create the wrong record.
2. Check for conflicting records. You generally cannot use a CNAME on a hostname that also has certain other record types attached.
3. Verify wildcard assumptions. A wildcard such as *.example.com does not always behave the way teams expect, especially if specific records already exist.
4. Check environment-specific hostnames. It is easy to deploy staging-api.example.com in the app config while only creating api-staging.example.com in DNS.
5. Verify the hostname in your reverse proxy or ingress layer. Even though NXDOMAIN is a DNS error, teams often discover the real problem by reviewing Nginx, ingress, or app environment variables together.

If the subdomain points to a server or proxy you manage, this pairs well with Nginx Reverse Proxy Setup Guide for Node.js, Docker, and SSL.

3. API domain not resolving after a deployment

When an API domain fails right after shipping, separate DNS from deployment logic:

1. Check whether the deployment changed infrastructure but not DNS. For example, a new load balancer or server IP may exist, but the A record still points to the old target.
2. Review CI/CD outputs. If your pipeline updates infrastructure, make sure DNS automation actually completed. Partial deployments are common in multi-step pipelines.
3. Check for environment drift. The production API hostname may be correct in one repository and different in another.
4. Confirm the provider-specific domain verification step. Some platforms will not serve traffic for a hostname until the expected DNS records exist exactly as requested.
5. Test the record directly. Query the hostname and compare it to the intended target shown in your hosting platform.

If your workflow uses automated deploys, revisit your pipeline design in GitHub Actions Deployment Guide: Build, Test, and Deploy Web Apps Reliably.

4. Vercel, Netlify, or managed hosting domain setup shows NXDOMAIN

Managed hosting platforms are usually straightforward once the records are exact, but small mismatches cause repeated failures.

1. Follow the platform’s required hostname and record type exactly. A root domain and a www subdomain often need different records.
2. Make sure the domain was added in the hosting dashboard first. Creating DNS before attaching the domain in the platform can create confusing validation errors.
3. Avoid duplicate records across providers. If the domain is delegated to one provider, update records there only.
4. Check proxy settings. If you use a proxied DNS mode, temporarily confirm whether DNS-only mode is needed for validation.
5. Wait before changing again. Replacing records every few minutes makes it harder to tell whether propagation or misconfiguration is the real problem.

For platform-specific walkthroughs, see How to Connect a Domain to Vercel Without DNS Errors and How to Connect a Domain to Netlify: DNS Records, SSL, and Common Fixes.

5. Local development hostname fails with NXDOMAIN

Local DNS troubleshooting looks different because the public DNS system may not be involved at all.

1. Check your hosts file. If you expect myapp.local or api.test to resolve locally, confirm the hostname is mapped to 127.0.0.1 or the correct local IP.
2. Review Docker or VM networking. A container name is not automatically a public or system-wide DNS entry.
3. Check local DNS services. Tools such as dnsmasq, local Kubernetes clusters, dev proxies, or framework-specific DNS helpers may need to be restarted.
4. Flush local caches. Browsers and operating systems can keep old answers longer than expected.
5. Use a consistent development TLD. Ad hoc names created by different team members often lead to unrepeatable setups.

If your local stack includes containers and reverse proxies, it may help to review Docker Deployment Tutorial for Small Production Apps alongside your dev networking setup.

What to double-check

Before you conclude that “DNS is broken,” pause and verify these details. They account for a large share of preventable NXDOMAIN cases.

Authoritative nameservers

Find out which nameservers are actually authoritative for the domain. If your registrar points to provider A but you are editing records in provider B, the hostname will still fail. This is especially common after migrations to Cloudflare or Route 53.

If you are setting up or reviewing a zone in Cloudflare, see Cloudflare DNS Setup Guide for Domains, Subdomains, and Common Record Types.

Record exists for the exact hostname

example.com and www.example.com are different names. So are api.example.com and app.example.com. Read the failing URL carefully. A surprising number of incidents come down to checking the wrong hostname.

Correct record type

Use the record type your target expects. A server IP usually needs an A or AAAA record. A hostname target usually needs a CNAME for subdomains. Root domain behavior varies by provider, so use the provider-supported option rather than forcing a CNAME where it does not belong.

Propagation versus cache

If you changed a record recently, compare answers from multiple resolvers. Your local machine may show NXDOMAIN while another resolver already sees the new record. That is not unusual during transitions. A dedicated propagation workflow helps here; see DNS Propagation Checker Guide: How to Verify Record Changes and Troubleshoot Delays.

Registrar versus DNS provider versus host

These are separate layers. The registrar controls domain registration and nameserver delegation. The DNS provider hosts the zone. The hosting platform serves the application. Problems often happen when teams assume changing one layer updates the others automatically.

App configuration

Sometimes the browser reports NXDOMAIN for a hostname generated by your app, not one you intended to expose. Check environment variables, API base URLs, OAuth callback URLs, and webhook endpoints. A typo in app config can send users to a non-existent hostname even when the primary domain works.

Email and verification records

TXT, MX, SPF, DKIM, and DMARC records do not usually cause browser NXDOMAIN directly, but editing them in the wrong zone is a strong signal that the whole DNS setup may be split across providers. If your team is also handling email, a structured review can help: SPF, DKIM, and DMARC Setup Guide for Google Workspace, Microsoft 365, and Custom Domains.

Common mistakes

This is the short list worth reviewing before making more changes.

• Editing the wrong DNS provider. The dashboard has the records you expect, but the domain is delegated somewhere else.
• Creating only the www record. The apex domain is left unconfigured, so www works and the root fails.
• Using the wrong host field format. Entering a full domain where only the label is expected, or the reverse.
• Deleting old records too early. During migrations, removing working records before the new target is confirmed creates unnecessary downtime.
• Confusing NXDOMAIN with connection errors. If the name resolves but the app is down, that is a different problem.
• Relying on one browser test. Browser cache can keep you stuck on an old answer.
• Changing nameservers and records at the same time without documenting the order. This makes root-cause analysis much harder.
• Forgetting local overrides. A stale hosts file entry or local DNS tool can make one machine disagree with the rest of the world.

A useful operating habit is to log each DNS change with four fields: what hostname changed, where it changed, what the intended target is, and when you expect to recheck it. That small discipline prevents many repeated investigations.

When to revisit

DNS troubleshooting guidance is worth revisiting whenever your inputs change, not only when something is already broken. Use this quick review before major changes or recurring planning cycles.

• Before a migration to a new DNS provider. Confirm delegation, export the existing zone, and map each hostname to its intended target.
• Before moving hosting platforms. Root domains, www redirects, API subdomains, and validation records should all be listed explicitly.
• Before seasonal traffic events or launches. Verify that critical domains and subdomains resolve from multiple resolvers before the busy period starts.
• When CI/CD workflows change. If deployments now create or update infrastructure automatically, confirm whether DNS automation is part of the process or still manual.
• When team ownership changes. DNS issues often appear after handoffs because knowledge lives in one person’s browser bookmarks and not in shared documentation.
• When local development conventions change. If you adopt new proxy tools, containers, or internal hostnames, refresh your local setup instructions.

For a practical final pass, use this action list the next time you see DNS_PROBE_FINISHED_NXDOMAIN:

1. Copy the exact failing hostname.
2. Identify the authoritative nameservers.
3. Open the active DNS zone, not the zone you assume is active.
4. Check whether the exact hostname has the required record.
5. Compare answers from more than one resolver.
6. Flush local cache only after verifying the authoritative setup.
7. Review the app or platform config that generated the hostname.
8. Document the fix so the same hostname pattern does not fail again.

If you treat NXDOMAIN as a layer-by-layer DNS problem rather than a general outage, the investigation gets much shorter. Most cases come down to an incorrect hostname, an inactive DNS zone, or a record that was never created where the internet is actually looking for it.