> 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

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.)
2. **Verify JSON syntax** — Malformed JSON will prevent records from being served
3. **Check name format** — Use `@` for the root domain, or a bare subdomain name (e.g., `www`, `grafana`)
4. **Confirm NFD version** — DNS requires NFD v3 or higher
5. **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).

**Solutions:**

1. **Ensure your NFD exists** — The NFD must be minted and active
2. **Check expiration** — Expired NFDs return placeholder responses
3. **Verify domain suffix** — You must query `*.algo.xyz`
4. **Check for typos** — Double-check the NFD name spelling

***

### 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 NXDOMAIN on a Deep Name

**Symptoms:** A deeply nested name (e.g. `a.key.api.patrick.algo.xyz`) returns `NXDOMAIN` 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.

**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.

***

### 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. **CNAME only for subdomains** — You cannot use CNAME for the root (`@`); use A record instead
3. **Check target exists** — Verify the CNAME target domain is accessible

***

## 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nf.domains/platform/manage/native-dns-for-nfds/testing-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.