When you try to move your Bluesky account to a new host or domain, you may see a “Migration token invalid” error. This error stops the account transfer process and leaves you stuck on your current provider. The root cause is almost always a mismatch in the token’s generation or application within Bluesky’s authentication system. This article explains why the token becomes invalid and provides step-by-step fixes to resolve the issue.
Key Takeaways: Fixing the Bluesky Migration Token Invalid Error
- Settings > Account > Migration > Generate Migration Token: Generates a unique, time-limited token for account transfer
- Token expiration window: The token is valid only for 15 minutes after generation, requiring a fresh token if the process stalls
- Manual DNS TXT record verification: Confirms domain ownership before Bluesky accepts the migration token
Why the Migration Token Becomes Invalid on Bluesky
The Bluesky migration token is a cryptographic string that proves you own the Bluesky account and want to move it to a new domain or hosting provider. Bluesky generates this token inside your account settings. The token includes a timestamp and a signature tied to your current account credentials.
The token becomes invalid for three primary reasons:
- Token expiration: The token expires 15 minutes after generation. If you generate it and then wait too long to use it, Bluesky rejects it as invalid.
- DNS record mismatch: The TXT record you add to your new domain’s DNS settings must match exactly what Bluesky expects. A typo in the record name or value makes the token invalid.
- Account credential change: If you change your password or handle after generating the token, the token’s signature no longer matches your account. Bluesky invalidates the old token immediately.
Steps to Generate and Apply a Valid Migration Token
- Check your current account handle and domain
Open Bluesky in a web browser. Go to Settings > Account. Verify your current handle is the one you want to migrate from. If you changed your password recently, wait 10 minutes before generating a token to avoid signature mismatches. - Generate the migration token
In Settings > Account, scroll to the Migration section. Click “Generate Migration Token.” A dialog box shows the token string. Copy it immediately to your clipboard. Do not close the dialog or navigate away. - Add the TXT record to your new domain
Log in to your domain registrar or DNS hosting provider. Create a new TXT record with the following values:
Name:_atproto.yournewdomain.com
Value:did=plc:yourdid(replaceyourdidwith your Bluesky DID, found in Settings > Account)
TTL: 300 seconds (5 minutes) or the lowest value allowed. - Wait for DNS propagation
DNS changes can take up to 15 minutes to propagate worldwide. Use a tool like whatsmydns.net to check if the TXT record is visible globally. Do not proceed until the record shows as published. - Enter the token in the new host
If you are migrating to a self-hosted PDS, open the PDS admin interface and paste the token into the migration form. If you are moving to a different Bluesky-compatible host, follow that host’s migration instructions. The token must be entered within 15 minutes of generation. If the token has expired, return to step 2 and generate a fresh token. - Confirm the migration
After entering the token, Bluesky checks the DNS TXT record. If the record matches, your account handle changes to the new domain. You will see a confirmation message in Settings > Account. Your old handle becomes available for release.
If Bluesky Still Shows Token Invalid After the Main Fix
Token expired during DNS propagation
DNS propagation can take longer than the token’s 15-minute validity window. If you generated the token before the DNS record was visible globally, the token expires before you can use it. Generate a new token after confirming the TXT record is live. Then immediately apply the new token.
DNS record has a typo or wrong value
Double-check the TXT record name and value. The name must be _atproto.yournewdomain.com exactly. The value must start with did=plc: followed by your exact DID. A missing underscore or a wrong DID makes the token invalid. Delete the incorrect record and add a corrected one. Wait for propagation and generate a fresh token.
Account handle already claimed by another user
If the new domain handle is already in use by another Bluesky account, the migration fails with a token invalid error. Bluesky does not allow two accounts to use the same handle. Verify that the handle is available by searching for it in the Bluesky app. If it is taken, choose a different handle or contact the current owner to release it.
Bluesky Migration Token: Token Generation vs DNS Verification
| Item | Token Generation | DNS Verification |
|---|---|---|
| Purpose | Proves you control the Bluesky account | Proves you control the new domain |
| Method | Bluesky generates a signed cryptographic string | You add a TXT record to your domain’s DNS settings |
| Expiration | 15 minutes after generation | No expiration, but must be present at migration time |
| Common failure | Token used after expiration or after password change | TXT record missing, misnamed, or with wrong DID value |
You can now resolve the “Migration token invalid” error by generating a fresh token after DNS propagation and verifying the TXT record is correct. For future migrations, always confirm DNS is fully propagated before generating the token. If you plan to migrate multiple accounts, generate and apply tokens one at a time to avoid confusion with different DID values.