DNS troubleshooting
Start here: is it a cache or a mistake
Almost every “my record is not being picked up” is one of two things, and one command separates them:
dig TXT _lockally-verify.yourcompany.com @ns1.yourprovider.com
Querying your authoritative nameserver directly bypasses every cache.
| Result | Meaning |
|---|---|
| The record is there | Your provider has it; you are waiting on a cache. Call /recheck |
| The record is not there | Your provider did not save what you think it did. Fix it there |
That distinction is worth making before anything else, because the two have completely different fixes and retrying only helps one of them.
Check the domain exists at all
dig yourcompany.com
NXDOMAIN means the domain is not registered. There is nowhere to publish
DNS and verification can never succeed. Lockally does not sell domains; buy it
from a registrar first.
This sounds too obvious to check, and it is the single most expensive failure in this area: a customer added a domain they had not yet bought, was told it was “registered” by wording we have since changed, and spent 23 minutes pressing Verify.
The five things that go wrong with records
The verification record at the wrong name. It goes at
_lockally-verify.yourcompany.com, not at the apex.
The token wrapped in a prefix. The value is the bare lkv-... token.
Not lockally-verify=lkv-....
Two SPF records. Only one TXT record on a domain may start v=spf1. Two
is a permanent error for every receiving server. Merge the includes into one.
The provider appending your domain twice. Many forms want the relative
host, so entering _lockally-verify.yourcompany.com produces
_lockally-verify.yourcompany.com.yourcompany.com. Use the host field from
the records array, which is already relative. If in doubt, publish it and
then dig it.
A truncated DKIM value. The key is long. Some editors trim it, some
providers split it into quoted chunks (which is correct). Compare what dig
returns against dkim_public_record from the API.
Domain errors, and what each one means
| Status | Title | What it means |
|---|---|---|
404 |
Domain not found |
Not on your account. Check spelling, and that you added it |
409 |
Domain claimed by another tenant |
Another account holds it. Not resolvable from the API; contact support |
409 |
Domain not verified |
Return-Path setup on an unverified domain. Verify first |
502 |
DNS lookup failed |
We could not query DNS at all. Transient; retry |
403 |
Upgrade required |
A paid-plan feature, such as a custom Return-Path, on Free |
403 |
Insufficient scope |
The key lacks domains:read or domains:write |
Note that /recheck needs domains:write, not read, because it also
reconciles state. A read-only key gets 403 on it.
The one that is not an error
POST /verify returning 200 with "verified": false is not a failure
response. The record was not found, and the current state is returned so you
can poll. Read the verified field rather than the status code.
Sending fails although the domain is verified
Verified means the ownership token was seen. It does not mean SPF, DKIM or MX exist, because verification never checks them.
So if a verified domain cannot send, or its mail lands in spam:
POST /v1/domains/{domain}/recheckfor live per-record status.- Check SPF and DKIM are actually published; mail without them is widely filtered even when we accept it.
- Check the sending address is allowed. Verification authorises the domain, but the rules on which addresses you may use are in Sender identity.
- Remember verification does not inherit:
mail.yourcompany.comneeds its own.
Still stuck
Quote the request_id from the error body. It is on every response, and it is
what lets support find your exact call rather than guessing from a timestamp.