Pourquoi un handle de domaine Bluesky est invalide, et comment le corriger
Comment Bluesky vérifie un handle de domaine : l’enregistrement TXT _atproto, le fichier atproto-did, le document DID, chaque vérification et les erreurs fréquentes.
Comment Bluesky vérifie un handle de domaine
Un handle est un nom de domaine. Bluesky accepte alice.example.com comme
handle quand il peut vérifier le lien dans les deux sens :
- Le domaine pointe vers votre compte. Soit un enregistrement DNS
TXTnommé_atproto.alice.example.comdont la valeur estdid=suivi de votre DID, soit le fichierhttps://alice.example.com/.well-known/atproto-diddont le seul contenu est votre DID. L’un des deux suffit. - Votre compte pointe vers le domaine. Votre document DID indique le
handle dans
alsoKnownAs, sous la formeat://alice.example.com. Bluesky l’y écrit quand vous changez de handle dans l’application.
Les règles sont dans la spécification des handles de l’AT Protocol. Pour les autres façons d’obtenir un handle, lisez le guide Comment obtenir un handle personnalisé sur Bluesky.
L’enregistrement à ajouter
| Handle | Hôte / Nom | Type | Valeur |
|---|---|---|---|
example.com | _atproto | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
alice.example.com (zone example.com) | _atproto.alice | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
Les interfaces DNS ajoutent votre zone au nom d’elles-mêmes : saisissez la
partie de _atproto.<handle> qui précède la zone, et non le nom complet. Le
vérificateur trouve la zone par une requête SOA et affiche l’hôte exact. La
valeur commence par did=, sans guillemets ni espaces : Bluesky lit une seule
valeur qui commence par did=, telle quelle, sans rien retirer.
Le fichier est l’autre méthode, pour un hébergement sans interface DNS. C’est du texte brut, servi avec le statut 200 :
did:plc:ewvi7nxzyoun6zhxrhs64oizCe que vérifie l’outil
L’outil fait sept vérifications, dans l’ordre. Chacune réussit, échoue,
avertit ou n’est pas faite, avec un code de raison (les réponses de l’API et
du MCP donnent ce code dans checks[].reason).
| Vérification | Échoue quand (raison) |
|---|---|
syntax | le domaine n’est pas un handle valide : plus de 253 caractères (too_long), une seule partie (single_label), une partie vide ou de plus de 63 caractères (label_length), un caractère autre que a–z, 0–9 et - (characters), un tiret au début ou à la fin d’une partie (hyphen), un domaine de premier niveau qui commence par un chiffre (tld_digit), un domaine de premier niveau réservé comme .local ou .example (disallowed_tld) |
dns | aucun enregistrement (missing), une espace avant did=, que Bluesky lit comme une absence d’enregistrement (leading_space), un DID sans did= (no_prefix), une valeur qui n’est pas did= et un DID valide (invalid_value), l’enregistrement sur le mauvais nom (wrong_host : la zone deux fois, le _atproto de la zone elle-même, ou le domaine lui-même), deux valeurs ou plus qui commencent par did=, même identiques (conflict) |
https | aucun fichier (missing : un 404 ou un 410), une page web au lieu du DID (html), plus que le DID (extra_content), un contenu de plus de 1 Ko (too_large), un autre statut (status) ; avertit quand le serveur ne répond pas (unreachable) |
agreement | l’enregistrement et le fichier donnent des DID différents (disagree) |
document | le document DID déclare un autre handle ou aucun (claims_other), ou n’existe pas (not_found) |
expected | le domaine pointe vers un autre compte que celui indiqué (mismatch) |
appview | Bluesky affiche handle.invalid (invalid), l’ancien handle (old_handle), ou ne fait pas encore correspondre le domaine au compte (unresolved) |
Une méthode absente ne pose pas de problème quand l’autre fonctionne : la
ligne réussit alors avec not_needed. Un problème sur la méthode que Bluesky
n’utilise pas est un avertissement, sauf deux valeurs DNS qui commencent par
did=, que le résolveur de Bluesky traite comme un échec. Le DNS l’emporte,
comme dans la spécification : un DID donné par le DNS et déclaré en retour par
le document DID vérifie le handle, quoi que réponde le serveur web.
Erreurs fréquentes
- La zone ajoutée deux fois. Une interface DNS ajoute votre zone au nom :
saisir le nom complet
_atproto.alice.example.comcrée_atproto.alice.example.com.example.com. Saisissez seulement l’hôte que montre le vérificateur (_atproto.alicedans la zoneexample.com). - L’enregistrement sur le nom de la zone. Pour
alice.example.com, un enregistrement sur_atproto.example.comdésigne le handleexample.com, pas le vôtre. Le vérificateur cherche un enregistrementdid=à cet endroit, sur la zone ajoutée deux fois et sur le domaine lui-même. - Le DID sans
did=. La valeur doit êtredid=did:plc:…, préfixe compris. - Une espace avant
did=. Bluesky lit la valeur telle quelle :did=…compte comme une absence d’enregistrement. - Un ancien enregistrement oublié. Bluesky lit une seule valeur qui
commence par
did=: deux, même avec le même DID, rendent le handle invalide. Ne gardez que le vôtre. - Une page web au lieu du fichier. Beaucoup d’hébergeurs répondent à toute adresse inconnue avec leur page d’accueil, statut 200. Le fichier doit contenir le DID seul.
- Le handle pas encore changé. Les enregistrements sont bons, mais votre document DID déclare encore l’ancien handle : définissez de nouveau le handle dans Paramètres → Compte → Handle dans l’application Bluesky.
- L’attente du DNS. Un changement peut mettre jusqu’à une heure à atteindre tous les résolveurs. L’outil ne garde jamais de réponse en cache : relancez-le.
Pas de DNS pour un bot
Un bot peut prendre un handle name.bluesky.bot à la place : Bluesky.bot sert
le fichier et change le handle pour vous. Voir
Obtenir votre handle, ou vérifiez si un nom est libre
avec le vérificateur de disponibilité de handle.
L’utiliser depuis du code
Le vérificateur est aussi une route d’API gratuite et un outil MCP,
check_custom_handle :
curl "https://bluesky.bot/api/v1/tools/custom-handle-checker?domain=alice.example.com"Chaque appel compte pour 2 dans les limites. Voir API des outils et serveur MCP.