How a Bluesky custom feed works, and how to debug it
The parts of a Bluesky custom feed: the generator record, the service DID, the #bsky_fg service, skeleton and hydrated feeds, and how to fix each health check.
The parts of a custom feed
A custom feed has two halves that live in different places:
- The record,
app.bsky.feed.generator, on its creator's account: its name, description, avatar, and adidfield naming the feed generator that serves it. Its address is the feed's AT URI,at://<creator>/app.bsky.feed.generator/<rkey>, and its bsky.app link ishttps://bsky.app/profile/<creator>/feed/<rkey>. - The feed generator, a server identified by that DID (a
did:webor adid:plc). Its DID document has a service with the id#bsky_fgand the typeBskyFeedGenerator, whoseserviceEndpointis the server's https address.
One generator can serve many feeds, each from its own record.
Skeleton and hydrated feed
When someone opens a feed, the app asks Bluesky's AppView for app.bsky.feed.getFeed. The AppView reads the record, resolves the generator's DID, finds its #bsky_fg endpoint, and calls app.bsky.feed.getFeedSkeleton there. The generator answers a skeleton: a list of post URIs, nothing else.
{
"feed": [
{ "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
],
"cursor": "1731567000000"
}The AppView then hydrates it: it fetches each post, its author and its counts, applies blocks, mutes and labels, and returns full post views. The generator never sees who reads the feed unless the viewer is signed in, in which case the request carries a token naming them.
The AppView also tracks each generator: isOnline says it reached the generator recently, isValid that its answers had the right shape. The feed inspector shows both.
The DID document
For a did:web, the document is served at https://<host>/.well-known/did.json; for a did:plc, the PLC directory holds it. A minimal one:
{
"@context": ["https://www.w3.org/ns/did/v1"],
"id": "did:web:feed.example.com",
"service": [
{
"id": "#bsky_fg",
"type": "BskyFeedGenerator",
"serviceEndpoint": "https://feed.example.com"
}
]
}The generator must also answer app.bsky.feed.describeFeedGenerator with the same DID and the AT URI of every feed it serves.
The health check, step by step
The inspector's health check runs only when you ask, and follows the same path as the AppView:
- Service DID. The record's
didmust be adid:webon a bare host name (no port, no path) or adid:plc. Otherwise, publish the record again with the right DID. #bsky_fgservice. The DID document must exist, be valid JSON whoseidis the DID, and hold a#bsky_fgservice of typeBskyFeedGeneratorwith an https endpoint.describeFeedGenerator.GET <endpoint>/xrpc/app.bsky.feed.describeFeedGeneratormust answer 200 with adidequal to the service DID and afeedslist.- The feed is listed. The feed's AT URI should be in that
feedslist. A missing feed is a warning: some generators serve feeds they do not list. getFeedSkeleton.GET <endpoint>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1must answer 200 with afeedarray. A 401 means the feed needs a signed-in viewer: it works in the app, but not for logged-out readers, nor in the inspector's preview.
Each request has 4 seconds and 64 KB, and the time it took is shown. The requests go through our safety checks: https on port 443 only, and never to a private or local address, so a generator on a home network or behind a tunnel to localhost fails the check even when the app reaches it through a public address.
Common fixes
- Offline, but the server works: check the endpoint in the DID document (a typo,
http://instead ofhttps://, a trailing path) and that the certificate is valid for that host. - Valid is false: the skeleton must be an object with a
feedarray of{ "post": "<at uri>" }items; extra fields are fine, other shapes are not. - The preview is empty but the skeleton is not: the posts it returns may be deleted, from blocked or taken-down accounts, or from authors who share only with signed-in users.
- It worked, then stopped: a
did:webgenerator that moved to a new host needs its DID document updated; adid:plcone needs a PLC operation.
The AT Protocol's custom feed tutorial and Bluesky's feed generator starter kit cover building one. Bluesky.bot runs its own generator for the bots feed; its DID document is at /.well-known/did.json.