Troubleshooting the Bluesky PDS (Personal Data Server)

Bluesky, one of the new Social Network contenders, recently made its first steps towards becoming properly federated with the launch of a self hosted option for the Personal Data Server. In other words, if you create an account on the PDS, all of your posts, media etc on Bluesky will ultimately be hosted on the PDS meaning that you, or another party you trust, hold the keys to your data. Migration of an existing account off bluesky servers and onto a PDS is possible, but currenly filled with so many disclaimers it’s probably not worth looking at in any serious manner yet.

It’s important to note that Bluesky themselves say that the PDS is not yet stable, and definitely not ready for prime time. That said, I set one up for a test account and from being in the Discord server for PDS admins (link on the main PDS github) it seems like there’s some common pain points if you’re doing something more complex that the automated installer can’t handle. Thus…. my troubleshooting guide.

I’m assuming you’ve already run through the setup guide on the repo and somethings gone wrong.

I suggest running through each section in turn, making sure each test works. For each domain I’ll be using as the PDS domain. Substitute your PDSes own domain. Example responses are cribbed from my live PDS, slightly adjusted to make it clear which parts will be different.

HTTPS Connectivity to XRPC

The PDS requires that the following traffic is forwarded to it. These calls can be tried in your web browser of choice.

  1. Call

This call should return some simple JSON showing the version of the PDS code you are running, e.g. {"version":"0.4.12"}

If this call fails with an HTTPS error, then you need to double check that your TLS Certificate is valid your your PDS domain such as

If this call fails with a 503 error ro a similar 5xx error, then it is likely that your reverse proxy isn’t able to talk to your PDS application / container. Double check your reverse proxy configuration for how it’s talking to the PDS. For example it should be sending traffic to the PDS on port 3000.

If you get a 404 error, then check that your reverse proxy is correctly forwarding all /xrpc path traffic to the PDS.

Websocket Connectivity

The PDS requires that websocket connections are correctly Upgraded and forwarded by your reverse proxy. Not every reverse proxy handles this by default, and this seems to be a common pitfall for people going off the ‘golden path’ that the DPS documentation describes.

  1. Get yourself a websocket client. EG in a browser extnesion (I use, or a CLI client if you prefer.
  2. Issue a websocket call to wss:// this should result in an open websocket connection.

If you enocunter problems here you need to look up how to correctly handle websockets with your Reverse Proxy, e.g. using the information at for NGINX.

Request Federation at this point

At this point we’ve checked as much as we can config wise without an account on the PDS to test with. I would really recommend subimtting your federation request at this point and waiting for it to be approved, if you haven’t already. As the rest of the troubleshooting requires an account, and not being federated yet can lead to spurious problems as the bsky network will refuse to talk to your PDS properly.

Request a crawl at this point

Now that you are federated, you should request a crawl, especially if you were federated prior to finding this guide and you have fixed a problem.

  1. Use the pdsadmin request-crawl command. Or take a look at the commands source and manually craft the curl request to your instance

HTTPS Connectivity to your PDSs subdomains

To support accounts being created using the subdomain of your PDS – which is how all the bsky apps require you sto sign up right now, it is important that you are correctly able to handle requests to subdomains. We’ll be using a freshly created account here, to ensure that the actual contents should be valid.

  1. Create an account on your pds. eg with pdsadmin account create or, as above, look at the commands source and manually craft the curl request
  2. Visit and enter and check that it shows as being valid by the HTTP method. You can ignore the DNS method for this test.

If it shows a TLS error, then ensure that your reverse proxy has a TLS Certificate configured for * to be used on all subdomains of; or that it can get certificates for subdomains of on demand (such as caddy does)

If you are getting a 404 error then ensure the following is setup

  • traffic for * is being forwarded to the PDS
  • traffic for .well-known/atproto-did is being forwarded to the PDS

If you are still having problems try loading in your web browser yourself. You should receive back something like did:plc:abc123def456ghi789

One final test to close the loop on the account

One final test would be to call in your web browser, using the did that matches the account you made in the last step. This should return a JSON document containing a bunch of information about your did, including that the handle is

That’s all folks

That’s all I’ve got. By my understanding if everything I’ve described here is working then your PDS is properly working and you should be able to do anything you want through the bsky clients, including changing your handle. I’ll be keeping an eye on the PDS Admin discord, and may update this as I see other pain points that people going off the golden path hit, and ways to trobuleshoot them.

Leave a Reply

Your email address will not be published. Required fields are marked *