# 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](./web/index.md).

## "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](./concepts/stewardship.md)
and [My upload looks lost](./cookbook/lost-upload.md).

## "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

```bash
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.
