Troubleshooting Bluesky "Invalid Handle" Issue On A Self-Hosted ATProto PDS

Troubleshooting Bluesky “Invalid Handle” Issue On A Self-Hosted ATProto PDS

September 5, 2025

(Updated Sept 12 2025 to clarify some handle verification elements.)

As a nerd for decentralized communication systems, I recently decided to take the plunge and set up my own self-hosted PDS. While deploying the PDS was buttery smooth, the first account I set up on Bluesky using this PDS kept encountering the “Invalid Handle” error on the profile. I could not find a succinct troubleshooting guide for this issue, so here is my attempt at one. All feedback very welcome – you can reach me at @dulanyw.bsky.social or @dulanyw@techhub.social

Step 1: Is It DNS?

As you set up your PDS and your first account, you will need to add records to your DNS entry for your domain.

An “A” entry for “example.com” pointing to your IP address
An “A” entry for “*.example.com” pointing to your IP address

The first two you can set up when you set up your PDS.

You will also need to consider handle verification. – a process used by ATProto to connect your DID to your handle, and prove that you control them both.

By default, your PDS should handle this for you via the .well-known method. If you visit https://{handle.pdsdomain}/.well-known/atproto-did , you should see the DID for your handle (like “did:plc:usiuhiuh...“). If this works, I would advise not touching it.

If you do want to touch it (again, not advised), you can use the TXT method, where you add a TXT entry to your DNS record.

Let's say you are setting up multiple accounts on the PDS, and the first is helloworld.example.com. The TXT entry on your DNS record will look like:

TYPE: TXT
Hostname: _atproto.helloworld.example.com
Value: “did=did:plc:iushdfisuhfuihsdfuhs...”

where whatever comes after “did=” is your actual DID for your account. (Note that this may be weirdly case sensitive! Everything should be lower case!)

How do you find your DID? You have a few options.

If you have command line access to your PDS, SSH into it, then run the command “pdsadmin account list” – you should see it under the heading “DID”.
If not, you should be able to go to “https://[your-pds-domain]/xrpc/com.atproto.identity.resolveHandle?handle=[your-handle]” (replacing the appropriate variables) and see the DID in the output.

It's important to note that if you decide to go the TXT route, you'll also need to add another A entry to your DNS record for this specific subdomain (so helloworld.example.com will need to point to your PDS's IP address). Adding just a TXT record will override the *.example.com entry and prevent your handle from resolving at all on your PDS.

Step 2: Check the debug site

Bluesky has a handy debug site that lets you check the state of DID verification. Enter the full handle (like “helloworld.example.com”) and check if it passes via either method. If you did the DNS record correctly, you should get green across the board for that method. If not, go back and make sure you set up the TXT record correctly. (Again, the “did=” piece may be weirdly case sensitive!)

Step 3: Time to poast

In the Bluesky app, write a post! We're going to check if the AppView can actually write to your PDS.

Once you post your post, go to pdsls.dev, which is a tool for directly inspecting PDS information. Enter your handle (like “@helloworld.example.com”), then, under collections, check app.bsky.feed.post. If posts are shown, you can mouse over them and see what was entered. If you can post from Bluesky and see the result both on Bluesky and pdsls, it means reading and writing to your PDS is working!

Step 4: Check your websocket connection and Host header

Bluesky needs to see the Host header being forwarded in the response, as well as a valid websocket connection. If you set up a custom configuration for your PDS system (like Traefik or NGINX to help coordinate other services on the same VM), these are common problems.

Go to Piehost Websocket Tester and enter “wss://[your pds domain]/xrpc/com.atproto.sync.subscribeRepos?cursor=0”. If connection is established, you're good! (Thanks to Casey Primozoc for this tip!)

If you're on a computer that has curl, you can check the Host header issue with the command “curl -v https://[your pds domain]/xrpc/com.atproto.identity.resolveHandle?handle=[account handle, like helloworld.example.com] \ -H “Host: [your pds domain]“. If the response comes back with a JSON containing your DID, the PDS is handling the host header correctly.

Step 5: Time to crawl

SSH into the machine hosting your PDS and use the command “pdsadmin request-crawl bsky.network”, which requests the Bluesky Firehose to pull the data from your PDS. Even after this runs, it may take a little while before it clears the invalid handle issue.

Step 6: Call the experts

There is a great Discord channel for fellow PDS touchers here, and they are happy to help people troubleshooting issues to the extent that they can.

Good luck!