Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Test IPFS DNSLink:

Quick Test (Short Output)

Use +short for concise results:

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

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

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:

  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:

  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

PreviousDNS Record TypesNextMarketplace

Last updated