How to Clear BlueSky PDS and Relay Identity Caches

A BlueSky handle change can feel broken even when the account identity is fine. The old handle may appear in one client, the new domain handle may work in another, and a scheduler may still see cached identity metadata for a while.

The important distinction is that AT Protocol accounts are anchored by DIDs. Handles are human-friendly and mutable; DIDs are the stable identifiers that should keep publishing workflows pointed at the right account during a rebrand.

BlueSky's resolving identities guide recommends identity caches for large backend services, with core metadata revalidated periodically and a maximum TTL of 24 hours.

What is actually cached?

A handle update can pass through several layers: DNS or HTTPS well-known handle resolution, the DID document, the PLC directory for did:plc accounts, the user's PDS, relays, AppViews, and any third-party service cache. Those layers do not all refresh at the same time.

That is why forcing one browser refresh rarely fixes everything. A backend service may need to re-resolve the handle, purge its local identity cache, or wait for DNS and AppView caches to catch up.

Start with handle resolution

Confirm that the new handle resolves to the expected DID. AT Protocol supports DNS TXT records and HTTPS /.well-known/atproto-did for handle resolution. The handle should resolve to the DID, and the DID document should point back to the current handle.

Use the BlueSky DID and PLC lookup helper to normalize the handle, open the public resolver, and keep the DID separate from the mutable handle.

Check the common cache layers

DNS cache: lower the TXT record TTL before a planned domain-handle change when possible.

HTTPS well-known cache: confirm the response body contains only the DID with no wrapper text.

PLC directory: verify the did:plc document and operation log reflect the expected handle and service data.

PDS session: reconnect or refresh the scheduler account if the PDS still exposes stale account metadata.

AppView cache: allow time for public profile metadata and hydrated handle displays to update.

Third-party cache: ask tools to purge their own identity cache or reconnect the account if they store handle-to-DID mappings.

When to purge and re-resolve

The BlueSky identity guide recommends retrying identity resolution when account data validation fails in certain ways, such as signature validation issues or service endpoint movement. For a scheduler, a failed publish attempt after a handle change should trigger a DID-first re-check before assuming the account is disconnected.

Do not create a second account or rebuild every scheduled post just because a handle display is stale. First confirm whether the underlying DID still matches the approved account.

A safer rebrand checklist

Record the account DID before the public handle change.

Prepare DNS TXT or HTTPS well-known verification before announcing the handle.

Confirm the new handle resolves to the same DID from a public resolver.

Reconnect third-party tools if they cache handle metadata aggressively.

Keep scheduled posts mapped to the DID, not just the visible handle text.

Delay launch-sensitive posts until profile displays and public links have stabilized.

Where ONYX fits

ONYX should treat the DID as the durable account identity behind the publishing queue. That makes corporate rebrands, domain-handle moves, and public profile updates less likely to break already-approved scheduling sequences.

The practical workflow is simple: verify the DID, resolve the handle, refresh the connection if needed, then keep the content calendar moving once the account identity is confirmed.

Plan BlueSky posts through ONYX after handle and DID checks are complete.