Troubleshooting

Common failure modes and how to read them.

“every vantage returns error”

Top-level status is error, every row shows error instead of retrievable/unretrievable.

Likely cause: none of the API calls completed.

• Wrong Bee URL? Confirm the URL responds: curl http://your-bee:1633/health should return JSON.
• Network unreachable? Firewall, VPN, DNS.
• Bee API auth. Some deployments gate the API; bee-check doesn’t currently send auth headers. Run against a node you can hit anonymously.

“vantage error: CORS rejection” (web only)

The browser blocked the cross-origin request. The Bee at that URL needs cors-allowed-origins to include the page’s origin. See Setup and CORS.

“vantage error: blocked: mixed-content” (web only)

The SPA is on HTTPS, your Bee URL is http://... and not on localhost. Either point at http://localhost:1633, or serve your Bee over HTTPS via a reverse proxy.

“stewardship says no but /bzz works”

Expected: stewardship walks the network retrieval path; /bzz serves from local. See the stewardship chapter and My upload looks lost.

“every chunk has very high latency”

The probe completes but chunk_stats shows multi-second p95. Possibilities:

• The probing node is far from the chunks’ neighborhood — every fetch is traversing many hops. Check proximity_to_root and per-chunk proximity.
• The Bee is under load or has a slow disk.
• The network neighborhood is degraded (run from another vantage to isolate).

“--reseed refused: batch not usable yet”

The chain hasn’t confirmed enough blocks. Wait a few minutes after buying the batch and retry. On Sepolia, batches can take several minutes to become usable on first buy.

“every chunk found locally but stewardship says no”

The node has the chunks pinned (so /chunks/{addr} returns them from local store) but the network retrieval that stewardship uses takes a different path — and that path can’t find peers with the chunks. Same root cause as “my upload looks lost”: chunks haven’t propagated. Re-seeding with a current batch typically resolves it.

“feed lookup failed: 404”

The Bee you’re probing has never seen an update for this (owner, topic) pair. First-time lookups on a feed can take 30-60s on Sepolia; the Bee caches results, so subsequent calls are fast. Wait and retry, or use a different vantage that has seen the feed before.

Getting more output

bee-check <ref> -v        # info: per-stage milestones
bee-check <ref> -vv       # debug: per-vantage results + every HTTP call
bee-check <ref> -vvv      # trace: per-chunk probe events

-vv is usually the sweet spot — it surfaces every underlying bee-rs HTTP call (method, URL, status, elapsed) which is normally the fastest way to a root cause. RUST_LOG still overrides the flag if you want fully custom filtering, e.g. RUST_LOG=bee_check=info,reqwest=debug bee-check ....

--output json includes every field unconditionally and is far more informative than the text rendering — useful for scripting and for sharing diagnostics.

For the web UI, the browser DevTools network tab shows every underlying HTTP call and its response — usually the fastest path to a root cause.