Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The stewardship probe

The core operation bee-check performs against every vantage is:

GET /stewardship/{reference}

This Bee endpoint walks the manifest at reference and tries to fetch every chunk through the network — using the probed Bee node as the requesting peer. It returns:

{ "isRetrievable": true | false }

isRetrievable: true means the probed node was able to reach every chunk of the content through Swarm retrieval (i.e. through other peers in the network, not just from its own local store).

Why “from this vantage” matters

The answer is not a global property of the reference. It’s the answer this specific Bee node got when it tried. Two nodes in different neighborhoods will commonly get different answers for the same reference, because:

  • chunks are stored close (by proximity) to their address, and
  • a node retrieving a chunk has to route a request that eventually reaches a peer in that chunk’s neighborhood.

A node in the chunk’s neighborhood gets a fast local-or-near answer. A node far from the chunk has to traverse more hops, which is more likely to time out or hit unresponsive peers.

This is why bee-check is built around multi-vantage probing: each --bee URL is a different perspective on retrievability, and the aggregate partial status is meaningful in its own right.

Why stewardship can disagree with /bzz

The most common surprise:

curl http://localhost:1633/stewardship/<ref>   # {"isRetrievable":false}
curl http://localhost:1633/bzz/<ref>/          # 200 OK with content

Both can be true. /bzz/{ref}/ serves the content using whatever path is fastest, which typically means the node’s local store if the chunks are pinned there. /stewardship/{ref} deliberately re-fetches through the network retrieval path to answer the question “can a peer who doesn’t have this locally actually get it?”

So if you uploaded with swarm-deferred-upload: true (default) and your node hasn’t yet pushed the chunks into the network, stewardship will say no even though /bzz happily serves them. This is the “my upload looks lost” case covered in the Cookbook.

What the timing tells you

bee-check records elapsed_ms for each vantage — wall-clock time from issuing the request to receiving the answer. Combined with the per-chunk drill-down you can often distinguish:

  • Fast yes — chunk is local or in the immediate neighborhood.
  • Slow yes — chunk had to traverse several hops; network is working but the probed node isn’t near the content.
  • Slow no — request timed out walking the network; possibly a garbage-collected chunk or a dead neighborhood.
  • Fast no — usually a hard error: 404 from the API, bad request, CORS rejection in the browser.

See also

Complement: the cold-download probe

bee-check --cold adds an orthogonal probe alongside stewardship: it streams GET /bytes/{ref} from each Bee URL (and GET /bzz/{ref}/ from each gateway), counting total bytes and timing the full transfer. Use it when stewardship and a manual /bzz request disagree — the cold-download will tell you whether bytes actually flow end-to-end, which catches HTTP-level problems (compression issues, content-length mismatches, mid-stream errors) that the chunk-graph walk doesn’t surface.