> For the complete documentation index, see [llms.txt](https://docs.nf.domains/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nf.domains/platform/manage/native-dns-for-nfds/testing-and-troubleshooting.md).

# Testing & Troubleshooting

Test and debug your NFD DNS configuration

After configuring your NFD DNS records, use this guide to verify they're working correctly and troubleshoot common issues.

***

## Testing Your DNS Records

Use the `dig` command to verify your records are resolving correctly.

### Test A Record

```bash
dig patrick.algo.xyz A
```

### Test AAAA Record

```bash
dig patrick.algo.xyz AAAA
```

### Test MX Records

```bash
dig patrick.algo.xyz MX
```

### Test TXT Records

```bash
dig patrick.algo.xyz TXT
```

### Test a Subdomain

```bash
dig www.patrick.algo.xyz CNAME
```

### Test Bluesky Verification

```bash
dig _atproto.patrick.algo.xyz TXT
```

**Test IPFS DNSLink:**

```bash
dig _dnslink.patrick.algo.xyz TXT
```

### Quick Test (Short Output)

Use `+short` for concise results:

```bash
dig +short patrick.algo.xyz A
dig +short foo.patrick.algo.xyz TXT
```

{% hint style="info" %}
You should see your configured records in the ANSWER SECTION of the response.
{% endhint %}

***

## NFD Segments (Subdomains)

A segment (e.g. `api.patrick.algo`) is its own NFD with its own owner, and it **always serves its own DNS records**. How a segment combines with the root NFD depends on ownership. See the [Subdomain and Delegation Model](/platform/manage/native-dns-for-nfds.md#subdomain-and-delegation-model) for the full explanation; the table below is a quick reference.

### Rules

* If no segment NFD is minted, the **root** NFD serves the subname (set an `api` record on `patrick.algo`).
* If a segment is owned by the **same account** as the root, the two are merged and **root records win** on a conflict.
* If a segment is owned by a **different account**, the **segment is authoritative**—the root's records pointing into it are ignored.
* Maximum depth: the `.algo` name may have at most **4 labels**, not counting leading `_`-prefixed service labels (e.g. `key.api.patrick.algo` resolves; `a.key.api.patrick.algo` is rejected).

### Quick reference

| Setup                                                         | Query                       | Resolves to                         |
| ------------------------------------------------------------- | --------------------------- | ----------------------------------- |
| Root only, `api` record on `patrick.algo`                     | `api.patrick.algo.xyz`      | root's `api` record                 |
| Segment `api.patrick.algo`, same owner, conflicting `@`/`api` | `api.patrick.algo.xyz`      | root's record (root wins)           |
| Segment `api.patrick.algo`, same owner, only segment has AAAA | `api.patrick.algo.xyz` AAAA | segment's record (merged)           |
| Segment `api.patrick.algo`, different owner                   | `api.patrick.algo.xyz`      | segment's own record (root ignored) |
| Segment exists but defines no records                         | `api.patrick.algo.xyz`      | placeholder                         |

***

## Troubleshooting

### Records Not Showing Up

**Symptoms:** `dig` returns no answer section or old data.

**Solutions:**

1. **Wait a few minutes** — There's caching at multiple levels (your local DNS, the resolver, etc.). The NFD resolver caches blockchain lookups for about a minute, and resolvers cache on top of that.
2. **Verify JSON syntax** — Malformed JSON will prevent records from being served
3. **Verify each record's *****value*****, not just the JSON** — One unparseable value makes the whole name fail with SERVFAIL rather than skipping just that record. A malformed CNAME is the worst case, since it takes down every record type at that name.
4. **Check name format** — Use `@` for the root domain, or a bare subdomain name (e.g., `www`, `grafana`)
5. **Confirm NFD version** — DNS requires NFD v3 or higher
6. **Check the NFD isn't listed for sale or expired** — either one replaces all your records with the placeholder A record
7. **Check for a CNAME at the same name** — a CNAME next to other records is served as an alias, so a `CNAME` query there returns nothing and an `A` query returns addresses without the CNAME (see [Apex CNAME Alongside Email or Verification Records](#apex-cname-alongside-email-or-verification-records))
8. **Watch the trailing dot** — A name with a trailing dot that isn't inside your NFD's zone (e.g. `_test._tcp.`) is re-rooted under your NFD, so it serves at an unexpected place like `_test._tcp.patrick.algo.xyz`. Use the `@` or `subdomain.@` form to be explicit.

***

### Getting NXDOMAIN

**Symptoms:** `dig` returns `NXDOMAIN` (domain does not exist).

NXDOMAIN means the **name** has no records of *any* type. If the name exists but has no record of the type you asked for, you get `NOERROR` with an empty answer section (NODATA) instead — that's the normal "wrong record type" result, not an error.

**Solutions:**

1. **Check the `name` field spelling** — NXDOMAIN on `sub.patrick.algo.xyz` usually means you have no record named `sub` (or `sub.@`) at all
2. **Ensure your NFD exists** — The NFD must be minted and active
3. **Verify domain suffix** — You must query `*.algo.xyz`
4. **Check for typos** — Double-check the NFD name spelling
5. **Wait, if the NFD is brand new** — not-found results are cached briefly, so a freshly minted NFD can keep returning NXDOMAIN for a short period

{% hint style="info" %}
**An expired or for-sale NFD does *****not***** return NXDOMAIN.** It returns the placeholder A record pointing at the NFD redirect service. If you're landing on a redirect page instead of your own site, that's the symptom to look for — not NXDOMAIN.
{% endhint %}

***

### Subdomain Returns Someone Else's Records

**Symptoms:** A subdomain like `api.patrick.algo.xyz` returns records you didn't set, and your root NFD's `api` record is ignored.

**Cause:** `api.patrick.algo` has been minted as a **separate segment NFD owned by a different account**. A different-owner segment is authoritative for its own subtree, so it serves its own records and any record you set on the root NFD pointing into that subtree is ignored. See the [Subdomain and Delegation Model](/platform/manage/native-dns-for-nfds.md#subdomain-and-delegation-model).

**Solutions:**

1. **Check segment ownership** — If you (or the same account) own both the root and the segment, the segment is merged and your root records win on a conflict.
2. **Set records on the segment** — To control a segment owned by a different account, edit that segment's NFD directly.

***

### Name Rejected or SERVFAIL on a Deep Name

**Symptoms:** A deeply nested name (e.g. `a.key.api.patrick.algo.xyz`) returns `SERVFAIL` or never resolves.

**Cause:** The `.algo` name exceeds the depth limit. A query name may have at most **4 labels**, not counting leading `_`-prefixed service labels. Over-deep names return SERVFAIL rather than NXDOMAIN, which resolvers retry — so this looks like an outage rather than a configuration mistake.

**Solutions:**

1. **Flatten the name** — `key.api.patrick.algo` (4 labels) resolves; `a.key.api.patrick.algo` (5 labels) does not.
2. **Service labels are exempt** — Underscore-prefixed labels like `_http._tcp` don't count toward the limit, so `_http._tcp.api.patrick.algo` is fine.

***

### Hosting Platform Won't Verify Your Domain

**Symptoms:** Vercel, Netlify or a similar platform rejects your NFD domain, or asks you to prove ownership of `algo.xyz` itself.

**Cause:** These platforms use the [Public Suffix List](https://publicsuffix.org/) (PSL) to decide what counts as a registrable domain. Until `algo.xyz` is on the PSL, they treat `algo.xyz` as the registrable domain and `patrick.algo.xyz` as a mere subdomain of it — so they ask for proof of ownership of the apex, which no NFD holder can provide.

This is not a DNS misconfiguration. Your records can be entirely correct and the verification will still fail.

**Solutions:**

1. **Check whether the platform offers an alternative verification method** — some accept a TXT record challenge on the subdomain itself rather than apex ownership
2. **Wait for PSL inclusion** — a submission for `algo.xyz` is pending. Once accepted, propagation to browsers and platforms follows their own update schedules, which can take weeks or months.

{% hint style="warning" %}
While PSL inclusion is pending, browser cookies scoped to `.algo.xyz` are **not isolated** between NFDs — a cookie set at that scope is readable by other NFD sites. Scope cookies to your own name (`patrick.algo.xyz`) rather than to `.algo.xyz`.
{% endhint %}

***

### Email Not Working

**Symptoms:** Emails to your domain bounce or don't arrive.

**Solutions:**

1. **MX record format** — Priority number must come before the hostname:
   * Correct: `"10 mail.example.com."`
   * Wrong: `"mail.example.com. 10"`
2. **Trailing dot** — MX hostnames must end with a period:
   * Correct: `"10 mail.example.com."`
   * Wrong: `"10 mail.example.com"`
3. **Add SPF record** — Most email providers require SPF:

   ```json
   {
     "name": "@",
     "type": "TXT",
     "rrData": ["\"v=spf1 include:_spf.yourprovider.com ~all\""],
     "ttl": 300
   }
   ```
4. **Add DKIM** — Check your email provider's documentation for required DKIM records
5. **Check DMARC** — Some providers require DMARC policy

***

### SSL Certificate Issues

**Symptoms:** Certificate Authority won't issue a certificate.

**Solutions:**

1. **Check CAA records** — If you have CAA records, ensure they authorize your CA:

   ```json
   {
     "name": "@",
     "type": "CAA",
     "rrData": ["0 issue \"letsencrypt.org\""],
     "ttl": 3600
   }
   ```
2. **Remove restrictive CAA** — If unsure, you can remove CAA records to allow any CA
3. **Wait for propagation** — Some CAs cache DNS results; wait and retry

***

### CNAME Not Working

**Symptoms:** Subdomain doesn't redirect to target.

**Solutions:**

1. **Use trailing dot** — Target hostname must end with a period:
   * Correct: `["myapp.vercel.app."]`
   * Wrong: `["myapp.vercel.app"]`
2. **Never use `@` as the target** — `@` is expanded only in the `name` field. As a target it means the DNS root, so `"rrData": ["@"]` points the record at `.` instead of at your NFD. It parses without error, so the breakage is silent. Write the target out in full: `["patrick.algo.xyz."]`.
3. **Check target exists** — Verify the CNAME target domain is accessible. If the target can't be resolved, the query returns SERVFAIL so resolvers retry rather than caching an empty answer.
4. **Check for a CNAME loop** — A CNAME pointing at its own name (e.g. `@` → `patrick.algo.xyz.`), two `.algo` names pointing at each other, or a chain longer than 8 hops returns SERVFAIL.

***

### Apex CNAME Alongside Email or Verification Records

**Symptoms:** You have a CNAME at `@` plus MX or TXT records there, and:

* `dig patrick.algo.xyz A` returns addresses but no CNAME line
* `dig patrick.algo.xyz CNAME` returns nothing
* Your hosting dashboard (Vercel, Netlify, …) reports the domain as misconfigured, even though the site loads

**Cause:** This is expected. Standard DNS forbids a CNAME sharing its name with other records, so NFD DNS serves it as an alias instead: A/AAAA come from the CNAME target but are returned under your own name, and MX, TXT and other types come from your stored records. Your email and verification records keep working. See [CNAME next to other records](/platform/manage/native-dns-for-nfds/dns-record-types.md#cname-next-to-other-records).

**Solutions:**

1. **Nothing, if the site and email work** — the dashboard warning is cosmetic.
2. **Use an A record at the apex if your host offers a fixed IP** (Netlify: `75.2.60.5`) — this satisfies dashboards and lets CDN hosts pick an edge near your visitors rather than near the DNS server.
3. **Move the CNAME to a subname** — e.g. put it on `www`, where it is the only record and is served as a normal CNAME.

***

## Resources

* **NFD Web App:** [app.nf.domains](https://app.nf.domains)
* **NFD API Documentation:** [api-docs.nf.domains](https://api-docs.nf.domains/)
* **nfd-coredns (open-source resolver):** [github.com/TxnLab/nfd-coredns](https://github.com/TxnLab/nfd-coredns)
* **Docker Image:** [txnlab/nfd-dns](https://hub.docker.com/r/txnlab/nfd-dns) — `txnlab/nfd-dns:latest`
* **TxnLab Resolver:** [txnlab.dev](https://txnlab.dev)
* **Nodely Resolver:** [nodely.io](https://nodely.io)