Bluesky “Invalid Handle”: causes and fixes

An invalid handle usually means a name and an account cannot be confirmed in both directions. Find which check fails before changing DNS or creating a new account.

By The Bluesky.bot team

Published:
Updated:
Reviewed:

The short answer

Bluesky needs two matching proofs: your handle resolves to the account’s DID, and that DID’s document claims the handle back. handle.invalid is the API placeholder for a handle that cannot be confirmed; it is not a domain to register. An application can also show an older result from its cache. The Handle specification defines both directions.

Check your handle now

This GET form opens the existing checker. Add the expected account DID there when the domain points to a different account. No sign-in is needed.

⚠Invalid Handle

Exact messages in the Bluesky app

  • Failed to change handle. Please try again.
  • Failed to verify handle. Please try again.
  • Invalid handle. Please try a different one.
  • Unable to resolve handle

App translations checked on November 16, 2026; wording can change in later releases. Source

The quoted strings come from a pinned version of Bluesky’s own translations, checked on 16 November 2026. An error while saving or verifying is a symptom, not proof that a particular DNS record is wrong.

How the two-way check works

How a handle is confirmed in both directions
  1. 1. Handle → DNS TXT or HTTPS proof
  2. 2. Proof → account DID
  3. 3. DID document → alsoKnownAs: at://handle

Only one forward method is required: the TXT value at _atproto.<handle> starts with did=, or the HTTPS file contains the DID alone. The DID document must then claim at://<handle>. For the underlying identity model, read handles and DIDs and the DID specification.

Which side fails?

  1. No DID from DNS or HTTPS: inspect the record’s name and value, or the file’s status and body. A network error means “could not check”, not “the name is abandoned”.
  2. A different DID: compare it with the DID of the account you intended. Do not copy an example DID or change a domain that belongs to another account.
  3. The right DID, another reverse handle: reselect the handle in that account. Editing DNS alone does not update its DID document.
  4. Both directions pass, an app still shows the old name: compare AppView results and allow caches to refresh; retry the account’s handle settings.
  5. An account is deleted, deactivated or taken down: DNS changes do not restore the account. Resolve its account status with the host first.

No TXT record, or the record is at the wrong name

What you see: dns: missing, or dns: wrong_host with the name where the record was found. In the example.com zone, you.example.com needs the relative TXT name _atproto.you. Some DNS panels append the zone, so entering the full name can create _atproto.you.example.com.example.com instead.

Fix: compare the resulting full hostname, not only the text typed into the panel. Put a single DID proof at _atproto.you.example.com. No TXT is needed if a valid HTTPS proof already works. Bluesky’s own instructions also show the subdomain form.

These dated outputs use the real checker engine with controlled dependency responses, fictional DIDs and reserved example.com names. They are documentation fixtures, not live DNS captures, user cases or a test of the project’s real domain. Each capture includes its provenance. No DNS or account was changed; this follows the issue’s initial default without live test domains.

Captured example: no TXT and no HTTPS proof
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"missing-txt.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {},
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "missing-txt.example.com"
  },
  "report": {
    "domain": "missing-txt.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "not_verified",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.missing-txt",
      "fullName": "_atproto.missing-txt.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://missing-txt.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "dns_missing"
  }
}
Captured example: the DNS panel appended the zone twice
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"wrong-host.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {
      "_atproto.wrong-host.example.com.example.com": [
        [
          "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        ]
      ]
    },
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "wrong-host.example.com"
  },
  "report": {
    "domain": "wrong-host.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "not_verified",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "wrong_host",
        "details": {
          "where": "doubled",
          "name": "_atproto.wrong-host.example.com.example.com",
          "values": [
            "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
          ]
        }
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.wrong-host",
      "fullName": "_atproto.wrong-host.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://wrong-host.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "dns_wrong_host"
  }
}

Wrong value format, or an old account’s DID

What you see: dns: invalid_value, no_prefix or leading_space. The TXT value is did=did:plc:… with your own full DID, not a profile URL. Literal quotes or spaces inside the value can prevent recognition; quotation marks used by a DNS lookup to display a TXT string are different from stored characters.

Fix: take the DID from the intended account’s handle settings. Remove extra formatting and obsolete conflicting TXT records. A syntactically valid DID can still be the wrong account: fill in expected account in the checker before replacing anything. The second capture has valid domain proof but fails that account comparison.

Captured example: a value that is not a DID
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"malformed-txt.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {
      "_atproto.malformed-txt.example.com": [
        [
          "did=not-a-did"
        ]
      ]
    },
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "malformed-txt.example.com"
  },
  "report": {
    "domain": "malformed-txt.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "not_verified",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "invalid_value",
        "details": {
          "values": [
            "did=not-a-did"
          ]
        }
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.malformed-txt",
      "fullName": "_atproto.malformed-txt.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://malformed-txt.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "dns_no_prefix"
  }
}
Captured example: the domain points to another DID
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"wrong-account.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {
      "_atproto.wrong-account.example.com": [
        [
          "did=did:plc:bbbbbbbbbbbbbbbbbbbbbbbb"
        ]
      ]
    },
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": {
      "id": "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb",
      "alsoKnownAs": [
        "at://wrong-account.example.com"
      ]
    },
    "appviewHandle": "wrong-account.example.com"
  },
  "report": {
    "domain": "wrong-account.example.com",
    "did": "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb",
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "dns",
    "verification": "verified",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "pass",
        "reason": "found",
        "details": {
          "values": [
            "did=did:plc:bbbbbbbbbbbbbbbbbbbbbbbb"
          ],
          "did": "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb"
        }
      },
      {
        "id": "https",
        "status": "pass",
        "reason": "not_needed",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "pass",
        "reason": "claims",
        "details": {
          "did": "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb",
          "handle": "wrong-account.example.com"
        }
      },
      {
        "id": "expected",
        "status": "fail",
        "reason": "mismatch",
        "details": {
          "dids": [
            "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb",
            "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
          ]
        }
      },
      {
        "id": "appview",
        "status": "fail",
        "reason": "unresolved",
        "details": {
          "handle": "wrong-account.example.com",
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      }
    ],
    "record": {
      "name": "_atproto.wrong-account",
      "fullName": "_atproto.wrong-account.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://wrong-account.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "did_mismatch"
  }
}

DNS and HTTPS return different DIDs

What you see: agreement: disagree. Fix: make both methods agree on the intended account, or remove the unused stale method. The Handle specification prefers DNS when both answer; disagreement does not automatically make a matching DNS-to-DID-to-handle chain invalid. Our checker reports the conflict separately from its verification result.

Captured example: DNS wins, but the file is stale
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"disagree-methods.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {
      "_atproto.disagree-methods.example.com": [
        [
          "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        ]
      ]
    },
    "https": {
      "status": 200,
      "text": "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb",
      "contentType": "text/plain",
      "redirects": 0
    },
    "didDocument": {
      "id": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "alsoKnownAs": [
        "at://disagree-methods.example.com"
      ]
    },
    "appviewHandle": "disagree-methods.example.com"
  },
  "report": {
    "domain": "disagree-methods.example.com",
    "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "both",
    "verification": "verified",
    "ok": false,
    "problems": 1,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "pass",
        "reason": "found",
        "details": {
          "values": [
            "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
          ],
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "https",
        "status": "pass",
        "reason": "found",
        "details": {
          "did": "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb",
          "redirects": 0
        }
      },
      {
        "id": "agreement",
        "status": "fail",
        "reason": "disagree",
        "details": {
          "dids": [
            "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
            "did:plc:bbbbbbbbbbbbbbbbbbbbbbbb"
          ]
        }
      },
      {
        "id": "document",
        "status": "pass",
        "reason": "claims",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
          "handle": "disagree-methods.example.com"
        }
      },
      {
        "id": "expected",
        "status": "pass",
        "reason": "match",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "pass",
        "reason": "ok",
        "details": {
          "handle": "disagree-methods.example.com"
        }
      }
    ],
    "record": {
      "name": "_atproto.disagree-methods",
      "fullName": "_atproto.disagree-methods.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://disagree-methods.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "dns_https_conflict"
  }
}

The HTTPS proof is a web page, login or proxy challenge

What you see: https: html, an HTTP 401/403, or an unreachable response. A browser rendering the home page is not the proof. Fix: serve the DID alone as text/plain at https://<handle>/.well-known/atproto-did, publicly, over HTTPS. Check the final status and body after any redirect. Keep the exception narrow to this public proof route; do not remove protection from unrelated application pages.

Redirects are allowed by the specification within a reasonable hop limit. A redirect that ends at a valid proof is not itself a failure; a login page, HTML shell or redirect loop is different. A working DNS method can also make the unused HTTPS problem a warning.

Captured example: an HTML home page instead of a DID
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"https-html.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {},
    "https": {
      "status": 200,
      "text": "<html><body>Home page</body></html>",
      "contentType": "text/html",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "https-html.example.com"
  },
  "report": {
    "domain": "https-html.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "not_verified",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "html",
        "details": {
          "status": 200,
          "redirects": 0
        }
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.https-html",
      "fullName": "_atproto.https-html.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://https-html.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "https_bad_body"
  }
}
Captured example: authentication required
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"https-login.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {},
    "https": {
      "status": 401,
      "text": "Authentication required",
      "contentType": "text/plain",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "https-login.example.com"
  },
  "report": {
    "domain": "https-login.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "could_not_check",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "status",
        "details": {
          "status": 401
        }
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.https-login",
      "fullName": "_atproto.https-login.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://https-login.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": null
  }
}
Captured example: a browser-verification challenge
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"https-challenge.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {},
    "https": {
      "status": 403,
      "text": "<html><body>Browser verification required</body></html>",
      "contentType": "text/html",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "https-challenge.example.com"
  },
  "report": {
    "domain": "https-challenge.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "could_not_check",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "status",
        "details": {
          "status": 403
        }
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.https-challenge",
      "fullName": "_atproto.https-challenge.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://https-challenge.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": null
  }
}
Control example: a redirect that succeeds
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"https-redirect.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {},
    "https": {
      "status": 200,
      "text": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "contentType": "text/plain",
      "redirects": 1
    },
    "didDocument": {
      "id": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "alsoKnownAs": [
        "at://https-redirect.example.com"
      ]
    },
    "appviewHandle": "https-redirect.example.com"
  },
  "report": {
    "domain": "https-redirect.example.com",
    "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "https",
    "verification": "verified",
    "ok": true,
    "problems": 0,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "pass",
        "reason": "not_needed",
        "details": {}
      },
      {
        "id": "https",
        "status": "pass",
        "reason": "found",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
          "redirects": 1
        }
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "pass",
        "reason": "claims",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
          "handle": "https-redirect.example.com"
        }
      },
      {
        "id": "expected",
        "status": "pass",
        "reason": "match",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "pass",
        "reason": "ok",
        "details": {
          "handle": "https-redirect.example.com"
        }
      }
    ],
    "record": {
      "name": "_atproto.https-redirect",
      "fullName": "_atproto.https-redirect.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://https-redirect.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "ok"
  }
}

The DID document still claims the old handle

What you see: document: claims_other, even though DNS finds the expected DID. Fix: sign in to the intended account, open its handle settings and verify/select the full domain again. A switch on another account or an incomplete host migration can leave the reverse claim elsewhere. Confirm which account you are using before saving; this guide does not repair a PDS migration.

Captured example: the reverse claim names old.example.com
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"reverse-claim.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {
      "_atproto.reverse-claim.example.com": [
        [
          "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        ]
      ]
    },
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": {
      "id": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "alsoKnownAs": [
        "at://old.example.com"
      ]
    },
    "appviewHandle": "reverse-claim.example.com"
  },
  "report": {
    "domain": "reverse-claim.example.com",
    "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "dns",
    "verification": "not_verified",
    "ok": false,
    "problems": 1,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "pass",
        "reason": "found",
        "details": {
          "values": [
            "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
          ],
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "https",
        "status": "pass",
        "reason": "not_needed",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "fail",
        "reason": "claims_other",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
          "handle": "old.example.com"
        }
      },
      {
        "id": "expected",
        "status": "pass",
        "reason": "match",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "pass",
        "reason": "ok",
        "details": {
          "handle": "reverse-claim.example.com"
        }
      }
    ],
    "record": {
      "name": "_atproto.reverse-claim",
      "fullName": "_atproto.reverse-claim.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://reverse-claim.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "doc_not_claiming"
  }
}

Both proofs work, but the app has not caught up

What you see: verification: verified with appview: old_handle, or different results across apps. Fix: check the current proof and DID document first, then retry Settings → Account → Handle, “I have my own domain”, and the verification step. These are the steps documented by Bluesky, not a guaranteed cache-purge command. DNS TTL and identity caches mean there is no universal propagation time.

Captured example: a valid chain and an older AppView handle
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"stale-appview.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {
      "_atproto.stale-appview.example.com": [
        [
          "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        ]
      ]
    },
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": {
      "id": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "alsoKnownAs": [
        "at://stale-appview.example.com"
      ]
    },
    "appviewHandle": "old.example.com"
  },
  "report": {
    "domain": "stale-appview.example.com",
    "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "dns",
    "verification": "verified",
    "ok": false,
    "problems": 1,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "pass",
        "reason": "found",
        "details": {
          "values": [
            "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
          ],
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "https",
        "status": "pass",
        "reason": "not_needed",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "pass",
        "reason": "claims",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
          "handle": "stale-appview.example.com"
        }
      },
      {
        "id": "expected",
        "status": "pass",
        "reason": "match",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "fail",
        "reason": "old_handle",
        "details": {
          "handle": "old.example.com"
        }
      }
    ],
    "record": {
      "name": "_atproto.stale-appview",
      "fullName": "_atproto.stale-appview.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://stale-appview.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "appview_stale"
  }
}

A .bluesky.bot handle was released or replaced

Our proof is HTTPS; you do not add DNS records for name.bluesky.bot. Releasing the name removes its claim. If the bot merely switched to another handle, the reservation can remain while the scheduled health check records the incident. Repeated confirmed failures remove live status; a public listing can remain in its 14-day grace period. An opted-in, confirmed alert address can receive one incident email. Verify a bot explains the states and how to switch/check again.

Fix: in the bot’s dashboard, confirm the account is active and still owns the claimed name, then use the switch/check controls. After a release, choose an available name; a diagnostic page cannot restore a reservation. The fixture below models absent proof after release using a reserved example domain; it does not query a real .bluesky.bot handle.

Captured example: a released name has no forward proof
Captured

Input

Controlled fixture: checkHandleSetup({"domain":"released-handle.example.com","expected":"did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"})

Captured output

{
  "provenance": "Controlled dependency fixture; no live DNS, HTTP, DID or AppView request. Fictional DIDs and reserved example.com names.",
  "observations": {
    "txt": {},
    "https": {
      "status": 404,
      "text": "Not found",
      "redirects": 0
    },
    "didDocument": null,
    "appviewHandle": "released-handle.example.com"
  },
  "report": {
    "domain": "released-handle.example.com",
    "did": null,
    "expected": {
      "input": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa",
      "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "method": "none",
    "verification": "not_verified",
    "ok": false,
    "problems": 2,
    "warnings": 0,
    "checks": [
      {
        "id": "syntax",
        "status": "pass",
        "reason": "valid",
        "details": {}
      },
      {
        "id": "dns",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "https",
        "status": "fail",
        "reason": "missing",
        "details": {}
      },
      {
        "id": "agreement",
        "status": "not_checked",
        "reason": "one_method",
        "details": {}
      },
      {
        "id": "document",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      },
      {
        "id": "expected",
        "status": "not_checked",
        "reason": "no_did",
        "details": {
          "did": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      {
        "id": "appview",
        "status": "not_checked",
        "reason": "no_did",
        "details": {}
      }
    ],
    "record": {
      "name": "_atproto.released-handle",
      "fullName": "_atproto.released-handle.example.com",
      "zone": "example.com",
      "zoneGuessed": false,
      "type": "TXT",
      "value": "did=did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "file": {
      "url": "https://released-handle.example.com/.well-known/atproto-did",
      "body": "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "bot": false,
    "result": "dns_missing"
  }
}

What our handle checks see

Recorded breaks by cause

As of

What the check observedRecorded incidentsShare of recorded breaks (%)
Bluesky shows another handle for the accountNot published: fewer than five contributors or no measured history.Not published: fewer than five contributors or no measured history.
Bluesky reports handle.invalidNot published: fewer than five contributors or no measured history.Not published: fewer than five contributors or no measured history.
The claimed name resolves to a different DIDNot published: fewer than five contributors or no measured history.Not published: fewer than five contributors or no measured history.
The account is no longer servedNot published: fewer than five contributors or no measured history.Not published: fewer than five contributors or no measured history.

Current public-directory bots; last 90 completed UTC days. These are incident transitions, not all daily checks. The entire split is withheld if a populated cause has fewer than five contributing bots. A missing value is not zero.

As of

Public live handles
56
Observed handle uptime (%)
100
Public bots contributing tracked minutes
56
Observed completed days
2
Median recovery time (hours)
Not published: fewer than five contributors or no measured history.
Recovered incidents
Not published: fewer than five contributors or no measured history.
Successful daily re-checks (%)
Not published: fewer than five contributors or no measured history.
Passed bot-days
Not published: fewer than five contributors or no measured history.
Observed bot-days
Not published: fewer than five contributors or no measured history.
Public bots contributing daily re-checks
Not published: fewer than five contributors or no measured history.
Completed UTC days with observations
Not published: fewer than five contributors or no measured history.
Calendar days since first observation in this window
Not published: fewer than five contributors or no measured history.

These figures concern currently public directory bots. Uptime is the share of tracked minutes without a recorded handle incident, not the share of successful checks. Recovery uses valid incident closures in the last 90 completed UTC days, excluding unresolved incidents. Old history is not backfilled.

The rate is passed bot-days divided by observed bot-days: only the last conclusive automated daily health re-check of each bot on each UTC day counts. It excludes manual checks, first/pending verifications, outage controls, network uncertainty and failures discarded by the outage guard. We use at most 90 completed UTC days, ending yesterday; days without observations are not passes. The calendar span starts at the first recorded day in that window. Counts and rate are withheld together unless five distinct bots contribute and every populated pass/fail group has five contributors. Collection starts with deployment; no earlier result is reconstructed. Endpoint latency remains unmeasured.

These figures describe currently public directory bots, including eligible grace-period listings, over at most 90 completed UTC days. They are not all Bluesky accounts or all service claims. shows_other_handle, handle_invalid, resolves_elsewhere and account_gone are observed symptoms, not proven DNS root causes. We do not infer a share of DNS-panel mistakes from them. Recovery counts only closed incidents; ongoing incidents are excluded from its median. Unobserved history is not backfilled, and small cause populations suppress the entire split.

Still stuck?

Use Bluesky support for account or app issues, and contact us for a .bluesky.bot claim. Include the failing check and capture date, never a password or OAuth token. If you run a bot and want to avoid managing DNS, read a handle for your bot and free handle options. A person does not need a bot handle to fix a custom domain.

Check a bot handle

Frequently asked questions

Does an invalid handle lose my followers?
Handle invalidation alone does not delete your account’s posts or followers. The DID identifies the account; repair the proof or select another handle in the same account.
How long does DNS take?
There is no fixed delay. DNS caches and identity-service caches can retain older answers. Confirm the authoritative record, allow its TTL to expire and recheck; changing the value repeatedly restarts the diagnosis.
Can I use a subdomain?
Yes. For you.example.com in the example.com zone, the TXT hostname is _atproto.you, with the full name _atproto.you.example.com. The proof and DID document must claim the complete handle.
Why is it invalid only in some apps?
Apps and identity services may refresh cached answers at different times. Compare the current DNS or HTTPS proof, the DID document and the AppView result before assuming the domain is still broken.

Sources