Why a Bluesky domain handle is invalid, and how to fix it
How Bluesky verifies a domain handle: the _atproto TXT record, the atproto-did file and the DID document, every check of the tool and the common mistakes.
How Bluesky verifies a domain handle
A handle is a domain name. Bluesky accepts alice.example.com as your handle
when it can check both directions of the link:
- The domain points to your account. Either a DNS
TXTrecord named_atproto.alice.example.comwhose value isdid=followed by your DID, or the filehttps://alice.example.com/.well-known/atproto-didwhose only content is your DID. One of the two is enough. - Your account points back to the domain. Your DID document lists the
handle in
alsoKnownAsasat://alice.example.com. Bluesky writes it there when you change your handle in the app.
The rules are in the handle specification of the AT Protocol. For the other ways to get a handle, read the guide How to get a custom handle on Bluesky.
The record to add
| Handle | Host / Name | Type | Value |
|---|---|---|---|
example.com | _atproto | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
alice.example.com (zone example.com) | _atproto.alice | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
DNS panels add your zone to the name on their own: type the part of
_atproto.<handle> before the zone, not the full name. The checker finds the
zone with an SOA lookup and shows the exact host. The value starts with did=
and has no quotes and no spaces: Bluesky reads exactly one value that starts
with did=, as is, nothing trimmed.
The file is the other way, for a host without a DNS panel. It is plain text, served with status 200:
did:plc:ewvi7nxzyoun6zhxrhs64oizWhat the checker checks
The tool runs seven checks, in order. Each one passes, fails, warns or is not
checked, with a reason code (the API and MCP answers give the code in
checks[].reason).
| Check | Fails when (reason) |
|---|---|
syntax | the domain is not a valid handle: over 253 characters (too_long), one part only (single_label), a part empty or over 63 characters (label_length), a character other than a–z, 0–9 and - (characters), a hyphen at either end of a part (hyphen), a top-level domain starting with a digit (tld_digit), a reserved top-level domain such as .local or .example (disallowed_tld) |
dns | no record (missing), a space before did=, which Bluesky reads as no record (leading_space), a DID without did= (no_prefix), a value that is not did= and a valid DID (invalid_value), the record on the wrong name (wrong_host: the zone twice, the zone's own _atproto, or the domain itself), two or more values starting with did=, even the same one (conflict) |
https | no file (missing: a 404 or a 410), a web page instead of the DID (html), more than the DID (extra_content), a body over 1 KB (too_large), another status (status); it warns when the server does not answer (unreachable) |
agreement | the record and the file name different DIDs (disagree) |
document | the DID document claims another handle or none (claims_other), or does not exist (not_found) |
expected | the domain points to another account than the one you gave (mismatch) |
appview | Bluesky shows handle.invalid (invalid), the previous handle (old_handle), or does not resolve the domain to the account yet (unresolved) |
A missing method is fine when the other one works: the row then passes with
not_needed. A problem with the method Bluesky does not use is a warning,
except two DNS values starting with did=, which Bluesky's resolver treats as
a failure. DNS wins, as in the specification: a DID from DNS that the DID
document claims back verifies the handle, whatever the web server answers.
Common mistakes
- The zone added twice. A DNS panel appends your zone to the name: typing
the full name
_atproto.alice.example.comcreates_atproto.alice.example.com.example.com. Type only the host the checker shows (_atproto.alicein the zoneexample.com). - The record on the zone's name. For
alice.example.com, a record on_atproto.example.comnames the handleexample.com, not yours. The checker looks for adid=record there, on the zone twice and on the domain itself. - The DID without
did=. The value must bedid=did:plc:…, the prefix included. - A space before
did=. Bluesky reads the value as it is:did=…counts as no record at all. - An old record left behind. Bluesky reads exactly one value starting
with
did=: two of them, even the same DID twice, make the handle invalid. Keep only yours. - A web page instead of the file. Many hosts answer every unknown address with their home page, status 200. The file must hold the DID alone.
- The handle not switched yet. The records are right, but your DID document still claims the old handle: set the handle again in Settings → Account → Handle in the Bluesky app.
- Waiting for DNS. A change can take up to an hour to reach every resolver. The checker never caches an answer: run it again.
Prefer no DNS for a bot
A bot can take a name.bluesky.bot handle instead: Bluesky.bot serves the
file and switches the handle for you. See
Get your handle, or check whether a name is free with
the handle availability checker.
Use it from code
The checker is also a free API route and an MCP tool, check_custom_handle:
curl "https://bluesky.bot/api/v1/tools/custom-handle-checker?domain=alice.example.com"Each call costs 2 against the limits. See Tools API and MCP server.