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

dig patrick.algo.xyz A

Test AAAA Record

dig patrick.algo.xyz AAAA

Test MX Records

dig patrick.algo.xyz MX

Test TXT Records

dig patrick.algo.xyz TXT

Test a Subdomain

dig www.patrick.algo.xyz CNAME

Test Bluesky Verification

dig _atproto.patrick.algo.xyz TXT

Quick Test (Short Output)

Use +short for concise results:

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

You should see your configured records in the ANSWER SECTION of the response.

---

NFD Segments (Subdomains)

If you own NFD segments (subdomains like mail.patrick.algo), their DNS records are automatically merged with the root NFD.

Rules

• Segment must be owned by the same account as the root NFD

• Root NFD records take priority if there's a conflict

• Maximum depth: 3 labels (e.g., a.b.patrick.algo)

Example

If you own both patrick.algo and api.patrick.algo:

• Records set on api.patrick.algo will be served for api.patrick.algo.xyz

• You can also set api records on patrick.algo if you don't have a separate segment

---

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

---

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

---

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:

   {
     "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:

   {
     "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

• NFD API Documentation: api-docs.nf.domains

• nfd-coredns (open-source resolver): github.com/TxnLab/nfd-coredns

• Docker Image: txnlab/nfd-dns — txnlab/nfd-dns:latest

• TxnLab Resolver: txnlab.dev

• Nodely Resolver: nodely.io