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

  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

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.

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

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.

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

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

PreviousDNS Record Types
NextMarketplace

Last updated