Tool documentation

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:

  1. The domain points to your account. Either a DNS TXT record named _atproto.alice.example.com whose value is did= followed by your DID, or the file https://alice.example.com/.well-known/atproto-did whose only content is your DID. One of the two is enough.
  2. Your account points back to the domain. Your DID document lists the handle in alsoKnownAs as at://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

HandleHost / NameTypeValue
example.com_atprotoTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz
alice.example.com (zone example.com)_atproto.aliceTXTdid=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:

text
did:plc:ewvi7nxzyoun6zhxrhs64oiz

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

CheckFails when (reason)
syntaxthe 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)
dnsno 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)
httpsno 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)
agreementthe record and the file name different DIDs (disagree)
documentthe DID document claims another handle or none (claims_other), or does not exist (not_found)
expectedthe domain points to another account than the one you gave (mismatch)
appviewBluesky 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.com creates _atproto.alice.example.com.example.com. Type only the host the checker shows (_atproto.alice in the zone example.com).
  • The record on the zone's name. For alice.example.com, a record on _atproto.example.com names the handle example.com, not yours. The checker looks for a did= record there, on the zone twice and on the domain itself.
  • The DID without did=. The value must be did=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:

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

Custom domain handle checker

Find out why your handle is invalid, and how to fix it.