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

Introduction

bee-check is a retrievability checker for Ethereum Swarm references — the Swarm analog of check.ipfs.network. You give it a 64-hex Swarm reference and one or more Bee API URLs; it tells you whether the reference is retrievable through each Bee node, how long retrieval took, which neighborhood each probe sits in relative to the chunk, and — with --per-chunk — exactly which chunks of the manifest are missing where.

It ships as two surfaces with identical capabilities:

  • bee-check — a Rust CLI, installable from crates.io, ideal for scripts, CI, and oncall workflows.
  • bee-check-web — a static SPA at ethswarm-tools.github.io/bee-check-web, ideal for ad-hoc diagnostics and sharing a reproducible link with a teammate.

Both speak the same spec_version: 1 JSON report shape, so a probe run on the CLI can be dropped onto the web page to visualize it (or vice versa).

Who is this for

  • Application developers uploading to Swarm who want to confirm their content is actually reachable from outside their own node.
  • Bee node operators investigating “user X says they can’t get ref Y from my gateway” reports.
  • Researchers measuring retrievability under different network conditions or across different node fleets.

What this book covers

  • Concepts — what “retrievable” actually means in Swarm, how the stewardship probe differs from a /bzz download, and what overlay / neighborhood / proximity-order numbers mean when they show up in a report.
  • CLI guide — install, every flag, output formats, the re-seed flow.
  • Web UI guide — running the SPA against your own Bee, dealing with CORS and HTTPS mixed-content, walking through the results panel.
  • Cookbook — worked scenarios: lost uploads, feed references, re-seeding from an old batch, multi-region probes.
  • Reference — the JSON shape, exit codes, and a feature-by-feature comparison to check.ipfs.network.

Conventions used in this book

code spans are CLI flags, HTTP paths, or JSON keys.

Note boxes flag subtle behaviors or footguns.

bee-check-the-CLI is referred to as just bee-check; the SPA is always bee-check-web to avoid ambiguity.

How to read it

If you’ve never used bee-check before, start with Quick start and skim the first three Concepts pages — that’s enough to read a report. If you’re triaging a specific problem, jump to the Cookbook.